information.
* Check out a working copy of a repository.
* View the history of changes to a project.
-* Explain why working copies of different projects should not overlap.
* Add files to a project.
-* Commit changes made to a working copy to a repository.
-* Update a working copy to get changes from the repository.
-* Compare the current state of a working copy to the last update from
- the repository, and to the current state of the repository.
+* Commit changes made to the working copy.
+* Get changes from an upstream repository.
+* Compare the current state of a working copy to the most recent
+ update from the upstream repository.
* Explain what "version 123 of `xyz.txt`" actually means.
Key points
* Version control is a better way to manage shared files than email or
shared folders.
-* The master copy is stored in a repository.
-* Nobody ever edits the master directory: instead, each person edits a
- local working copy.
-* People share changes by committing them to the master or updating
- their local copy from the master.
+* People share their changes by committing them to public repositories
+ and fetch other's changes by updating their local copy from public
+ repositories.
* The version control system prevents people from overwriting each
- other's work by forcing them to merge concurrent changes before
- committing.
+ other's work by making merges explicit.
* It also keeps a complete history of changes made to the master so
that old versions can be recovered reliably.
* Version control systems work best with text files, but can also
handle binary files such as images and Word documents.
* Every repository is identified by a URL.
-* Working copies of different repositories may not overlap.
-* Each changed to the master copy is identified by a unique revision
- number.
+* Each change to the master copy is identified by a unique revision
+ ID.
* Revisions identify snapshots of the entire repository, not changes
to individual files.
* Each change should be commented to make the history more readable.
* Commits are transactions: either all changes are successfully
committed, or none are.
-* The basic workflow for version control is update-change-commit.
-* `svn add <em>things</em>` tells Subversion to start managing
- particular files or directories.
-* `svn checkout $URL` checks out a working copy of a repository.
-* `svn commit -m "$MESSAGE" $THINGS` sends changes to the repository.
-* `svn diff` compares the current state of a working copy to the state
- after the most recent update.
-* `svn diff -r HEAD` compares the current state of a working copy to
- the state of the master copy.
-* `svn history` shows the history of a working copy.
-* `svn status` shows the status of a working copy.
-* `svn update` updates a working copy from the repository.
Merging conflicts
=================
* Explain what causes conflicts to occur and how to tell when one has
occurred.
* Resolve a conflict.
-* Identify the auxiliary files created when a conflict occurs.
Key points
----------
* Conflicts must be resolved before a commit can be completed.
-* Subversion puts markers in text files to show regions of conflict.
-* For each conflicted file, Subversion creates auxiliary files
- containing the common parent, the master version, and the local
- version.
-* `svn resolve $FILES` tells Subversion that conflicts have been
- resolved.
+* Most version control systems put markers in text files to show
+ regions of conflict.
Recovering old versions
=======================
Key points
----------
-* Old versions of files can be recovered by merging their old state
- with their current state.
-* Recovering an old version of a file does not erase the intervening
+* Recovering an old version of a file may not erase the intervening
changes.
* Use branches to support parallel independent development.
-* `svn revert` undoes local changes to files.
-* `svn merge` merges two revisions of a file.
Setting up a repository
=======================
Key points
----------
-* `svnadmin create $NAME` creates a new repository.
* Repositories can be hosted locally, on local (departmental) servers,
on hosting services, or on their owners' own domains.
Key points
----------
-* `$Keyword: …$` in a file can be filled in with a property value each
- time the file is committed.
* Put version numbers in programs' output to establish provenance for
data.
-* `svn propset svn:keywords $PROPERTY $FILES` tells Subversion to
- start filling in property values.
Version control is the most important practical skill we introduce.
-as the last paragraph of the introduction above says, the workflow
-matters more than the ins and outs of any particular tool. By the end
-of 90 minutes, the instructor should be able to get learners to chant,
-"Update, edit, merge, commit," in unison, and have them understand
-what those terms mean and why that's a good way to structure their
-working day.
+By the end of 90 minutes, the instructor should be able to get
+learners to fetch upstream updates, make local edits, and submit their
+changes upstream and why that's a good way to structure development.
Provided there aren't network problems, this entire lesson can be
-covered in 90 minutes. The example at the end showing how to use
-Subversion keywords to track provenance is the "ah ha!" moment for
-many learners. If time is short, skip the material on recovering old
-versions of files in order to get to this section instead. (The fact
-that provenance is harder in Git, both mechanically and conceptually,
-is one reason to keep teaching Subversion.)
-
-Prerequisites
--------------
-
-* Basic shell concepts and skills (`ls`, `cd`, `mkdir`, editing
- files).
-* Basic shell scripting (for the discussion of provenance).
+covered in 90 minutes.
Teaching notes
--------------
this really has to be the last version" to motivate version control
as a better way to collaborate and as a better way to back work up.
-* Version control is typically taught after the shell, so collect
- learners' names during that session and create a repository for them
- to share with their names as both their IDs and their passwords.
- The easiest way to create the repository is to use a server managed
- by an ISP such as Dreamhost, or on SourceForge, Google Code, or some
- other "forge" site, all of which provide web interfaces for
- repository creation and management. If your learners are advanced
- enough to be using SSH, you can instead create it on any server they
- can access, and connect with the `svn+ssh` protocol instead of
- HTTPS.
-
-* Be very clear what files learners are to edit and what user IDs they
- are to use when giving instructions. It is common for them to edit
- the instructor's biography, or to use the instructor's user ID and
- password when committing. Be equally clear *when* they are to edit
- things: it's also common for someone to edit the file the instructor
- is editing and commit changes while the instructor is explaining
- what's going on, so that a conflict occurs when the instructor comes
- to commit the file.
-
* Learners could do most exercises with repositories on their own
machines, but it's hard for them to see how version control helps
collaboration unless they're sharing a repository with other
learners. In particular, showing learners who changed what using
- `svn blame` is only compelling if a file has been edited by at least
- two people.
-
-* If some learners are using Windows, there will inevitably be issues
- merging files with different line endings. `svn diff -x -w` is
- supposed to suppress differences in whitespace, but we have found
- that it doesn't always work as advertised.
+ `blame` is only compelling if a file has been edited by at least two
+ people.
--- /dev/null
+In addition to the generic version control objectives and points.
+
+Basic use
+=========
+
+Learning objectives
+-------------------
+
+* Explain why working copies of different projects should not overlap.
+
+Key points
+----------
+
+* The master copy is stored in a repository.
+* Nobody ever edits the master directory: instead, each person edits a
+ local working copy.
+* The basic workflow for version control is update-change-commit.
+* `svn add <em>things</em>` tells Subversion to start managing
+ particular files or directories.
+* `svn checkout $URL` checks out a working copy of a repository.
+* `svn commit -m "$MESSAGE" $THINGS` sends changes to the repository.
+* `svn diff` compares the current state of a working copy to the state
+ after the most recent update.
+* `svn diff -r HEAD` compares the current state of a working copy to
+ the state of the master copy.
+* `svn history` shows the history of a working copy.
+* `svn status` shows the status of a working copy.
+* `svn update` updates a working copy from the repository.
+
+Merging conflicts
+=================
+
+Learning objectives
+-------------------
+
+* Identify the auxiliary files created when a conflict occurs.
+
+Key points
+----------
+
+* For each conflicted file, Subversion creates auxiliary files
+ containing the common parent, the master version, and the local
+ version.
+* `svn resolve $FILES` tells Subversion that conflicts have been
+ resolved.
+
+Recovering old versions
+=======================
+
+Key points
+----------
+
+* Old versions of files can be recovered by merging their old state
+ with their current state.
+* Recovering an old version of a file does not erase the intervening
+ changes.
+* `svn revert` undoes local changes to files.
+* `svn merge` merges two revisions of a file.
+
+Setting up a repository
+=======================
+
+Key points
+----------
+
+* `svnadmin create $NAME` creates a new repository.
+
+Provenance
+==========
+
+Key points
+----------
+
+* `$Keyword: …$` in a file can be filled in with a property value each
+ time the file is committed.
+* `svn propset svn:keywords $PROPERTY $FILES` tells Subversion to
+ start filling in property values.
--- /dev/null
+In addition to the generic version control notes.
+
+The example at the end showing how to use Subversion keywords to track
+provenance is the "ah ha!" moment for many learners. If time is
+short, skip the material on recovering old versions of files in order
+to get to this section instead. (The fact that provenance is harder
+in Git, both mechanically and conceptually, is one reason to keep
+teaching Subversion.)
+
+Teaching notes
+--------------
+
+* Version control is typically taught after the shell, so collect
+ learners' names during that session and create a repository for them
+ to share with their names as both their IDs and their passwords.
+ The easiest way to create the repository is to use a server managed
+ by an ISP such as Dreamhost, or on SourceForge, Google Code, or some
+ other "forge" site, all of which provide web interfaces for
+ repository creation and management. If your learners are advanced
+ enough to be using SSH, you can instead create it on any server they
+ can access, and connect with the `svn+ssh` protocol instead of
+ HTTPS.
+
+* Be very clear what files learners are to edit and what user IDs they
+ are to use when giving instructions. It is common for them to edit
+ the instructor's biography, or to use the instructor's user ID and
+ password when committing. Be equally clear *when* they are to edit
+ things: it's also common for someone to edit the file the instructor
+ is editing and commit changes while the instructor is explaining
+ what's going on, so that a conflict occurs when the instructor comes
+ to commit the file.
+
+* If some learners are using Windows, there will inevitably be issues
+ merging files with different line endings. `svn diff -x -w` is
+ supposed to suppress differences in whitespace, but we have found
+ that it doesn't always work as advertised.