This is a page of notes about using Subversion (SVN).
- CDS repository (until we switch to using SVN on SourceForge): https://svn.cds.caltech.edu/subversion/mhucka/
Checking out a copy for the first time
Before you can do anything, you will need to check out a copy of a tree into a local sandbox:
- create a directory inside of which you want to put the sandbox copy
- cd into that directory
svn checkout REPO/MODULE --username LOGIN, where
REPOis the repository server path (e.g.,
MODULEis the name of the project or module you want to check out (e.g.,
LOGINis the login you were given on the SVN repository server
Here is a complete example:
svn checkout https://svn.cds.caltech.edu/subversion/mhucka/test-suite --username mhucka
SVN caches your username and password. After the first time using a given repository, you won't need to supply the username or password again.
The SVN cycle
Once you have a local sandbox copy of a project, your standard usage pattern will generally be:
- Status: run
svn statusin your sandbox to find out the status of all local files and subdirectories relative to the repository. This is useful for finding out whether there have been changes in the repository and what would happen if you issued a
commit(see below). Use
svn help statusto find out the meaning of the status codes.
- Update: run
svn updatein the directory to update your sandbox copy with changes made to the central repository. Do this frequently to stay current with changes that other people are making. This command will print a line for every action taken; each line will have a single upper-case character in the left-most column indicating the type of update that was done to that file or directory. The main thing to watch for here is the C character, which indicates that a conflict occurred.
- Edit: make changes to your local sandbox files. To add, delete, or move files to/from/in the repository, use the following commands:
svn add fileto add
fileto the repository. The file must exist in your local sandbox.
svn delete fileto delete
filefrom the repository. It will also be deleted from your sandbox.
svn move oldname newnameto move file
- Commit: Add/delete/move operations will not take effect immediately; to make them actually take effect, issue the
svn commitcommand. You will need to provide a log message. If you're using the command line version of the svn client, you can type it as a string like this:
svn commit -m"The log message."
Alternatively, if you have configured your svn installation to use an editor, and you don't supply the -m argument, svn will invoke the editor for you to type a log message. (This can be the source of confusing errors: on Unix-like systems, if you have a screwed-up value for your
EDITOR environment variable, invoke svn commit will produce a confusing error about the failure involving the error, and it won't be completely obvious that the commit has failed because of this rather than a genuine problem involving the repository or the files.)
Dealing with conflicts
(Text borrowed from http://tableau.stanford.edu/~mwest/group/Subversion_Quick_Reference) If you see a
C character for a file after running
svn update or
svn status, it indicates a conflict in that file. This occurs if both another user and you have edited the same portion of a file and Subversion was unable to automatically merge the changes.
If this occurred during an
svn update, SVN will create four files in the directory in your sandbox:
filenameis Subversion's best attempt at merging your local changes with the repository copy. Conflicts in the file are bracketed by
filename.mineis the copy of filename as it existed in your directory before you did the update.
filename.rOLDREVis the copy of filename that you last checked out before editing it.
filename.rNEWREVis the copy of filename that you just checked out, containing the other user's changes.
You need to use the contents of these files to update your copy of filename to include all of the changes from both you and the other users, adding or discarding changes as you wish. You then must run:
svn resolved filename
This tells Subversion that the conflict is resolved, and so it will let you commit again.
Other useful tips
- What's the revision number of a local sandbox tree? Use
svnversion(yes, one word, no space).
- Who changed/created this line of code? Use
svn annotate file. It will print each line of
fileand provide an annotation at the beginning of the line listing the author and revision number for the last change to that line.
- How can I view the contents of a file at a given revision number? Use
svn cat --revision=NUMBER file.