Subversion Basic Use - Ece

Subversion Basic Use

From Ece

Jump to: navigation, search

This guide covers the basic use of Subversion. For information about creating and merging branches and tagging "snapshots" of the repository, see Subversion Branches and Tags. The basic Subversion tasks are covered in these two articles using command-line examples. They are recommended reading, even if you plan to use TortoiseSVN—a GUI client for Windows—as the TortoiseSVN article may not cover every concept included here.

Also, it is recommended that you first understand some basic concepts before you start. And for a more complete, excellent coverage of Subversion, see the (free) official online book Version Control with Subversion. 

Note: Yavin is running Subversion 1.4.  You may connect with a v1.4 or v1.5 client.
However, some v1.5 features, like merge tracking, will not be supported.

Contents

Acquiring the Subversion Client

Linux/UNIX

If you are running a flavor of Linux or UNIX on your personal machine, the best way to get Subversion will depend on your distribution. If your distribution has an established package distribution system, that would probably be your preferred channel. The Subversion website does maintain some links to binary packages produced by third parties.

Of course, you can also run the Subversion client directly on Yavin, using your home directory as your checkout space for storing a local working copy of the repository.

Windows

If you want to follow along with the command-line examples in this guide, you should install the command-line client produced by CollabNet. CollabNet will require you to create an account before allowing you to download.

You might prefer to install TortoiseSVN alongside or instead of the command-line client. TortoiseSVN is a Subversion GUI client that integrates with the Windows shell.

Basic Tasks

The primary client program in Subversion is svn. To perform an operation, you invoke a subcommand in the form svn subcommand.

All examples below will use the following base repository URL: 

svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/

Also, all examples will use a Linux/UNIX syntax form for directories. If you are a Windows user choosing the command-line client over a GUI like TortoiseSVN, you should be savvy enough to correctly specify Windows paths on the command-line as well.

Connecting to a Repository

For a full explanation of repository URLs and connection specifics, see Connecting to a Subversion Repository.

Getting Help

The subcommand help provides information about svn or a subcommand. It is invoked in the form svn help subcommand. For example, to get help on the subcommand checkout, type: 

svn help checkout

To get a listing of all available subcommands and their aliases (e.g., you can use co for checkout), type: 

svn help

Importing an Existing File Tree

The import subcommand can be used to add an entire directory tree to a repository in one step.

For example: 

svn import path/to/mytree/ svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/desired/path/

Note that this bypasses the usual checkout process, and you will still need to perform a checkout to get a working copy of the project.

Checking out a Working Copy

The checkout subcommand is used to check out a working copy form a repository. For example: 

svn checkout svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/ mylocalcopy

will checkout a working copy of the repository into a local directory mylocalcopy/.

To checkout an older revision, a revision number can be specified. 

svn checkout -r 9 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/

For more details on specifying revisions, see revision specifiers in the online Subversion book.

Making Local Changes

Once you have a working copy, you can start making changes in your favorite editor.

Additionally, you can use various commands to make changes to your working copy.

  • When you create a new file or place a new file in your working copy folder, the add subcommand is used to bring the file under version control, so that the next time you commit, that file will be added to the repository.
  • The delete subcommand does just what it says. On the next commit, the file will no longer exist in the current repository revision (although it will still exist in previous revisions).
  • The mkdir subcommand creates a new directory and adds it to version control. It is identical to using the system command mkdir followed by svn add.
  • The copy subcommand makes a copy of a file and adds it to version control. Subversion will record the fact that a copy took place, so this is not equivalent to using the system command cp followed by svn add. The copy subcommand also has more advanced uses, such as creating branches and tags or resurrecting a file deleted in a previous revision.
  • The move subcommand can move/rename a file, and is identical to a combination of svn copy and svn delete.

Examining Local Changes

The status subcommand uses a list of status codes (see link) to show the status of your files, such as added, modified, etc. By default, it shows only those files with interesting status information. Adding the --verbose option will list all files.

The diff subcommand can be used to view the local modifications you've made to a file. For example, after modifying a file foo.c, look at the changes with: 

svn diff foo.c

This will output the contents of the file, including changes.

  • Removed lines will be prefaced with -.
  • Added lines will be prefaced with +.
  • A change within a line is represented as a removed line (original state) followed by an added line (current state).

Reverting Local Changes

You can undo all changes made to a file since the last checkout or commit using the revert subcommand: 

svn revert foo.c

Updating the Working Copy

As you edit your working copy of the repository, others in your group may be doing so as well. In fact, in an active development team, it is quite likely that others have committed changes to the repository since your last checkout or commit.

So when you finish making your changes and attempt to commit them, Subversion must handle this carefully. It cannot simply allow you to directly commit your changes, because then the current revision after you commit would not include any of their latest changes. So, Subversion requires that you update your working copy with any new repository changes before it will allow you to commit.

You accomplish this with the update subcommand. Any changes that have been committed to the repository since your last checkout or commit (i.e. since the revision to which your working copy corresponds) will be merged into your working copy. Generally speaking, if your team is communicating well, than your changes—even if you're working on the same file—will not overlap, and Subversion can seamlessly merge them.

Note: Even if there are no overlapping changes and Subversion quietly merges all changes into your working copy, that does not mean the changes are compatible. It is up to you, the human being, to make sure your teammates changes work with your own.

Resolving Conflicting Changes

Sometimes updating your working copy will result in a state of conflict if your local changes and your teammates committed changes overlap. Depending on your version of the Subversion client (1.4 vs. 1.5), you may be interactively informed of files in a state of conflict, and given the option to immediately deal with the conflict. See the nightly build of the updated manual for more information on interactive conflict resolution.

If you are using Subversion 1.4 (or if you postpone all conflict resolution in v1.5), your working copy is left in a state of conflict, and you will not be allowed to commit until it is resolved. You can recognize a state of conflict by the letter C next to a filename when you perform svn update. For each conflicted file, Subversion does the following:

  • Places conflict markers inside your document. This would look something like: 
Here are some lines that are common
to both my working copy and the current revision
of the repository, but the next few lines are in conflict.

<<<<<<< .mine
In my working copy, these lines look
just like this, and so I can review them here.
=======
These lines belong to my teammate, and
I can see them here below the equal signs,
ended by a line of >'s and the current repository revision.
>>>>>>> .r22
Finally, this is a line that was common to our files.
  • Places three extra reference files in your directory. For example, if your last commit produced revision 18, and the current repository revision is 22:
    • foobar.c.mine — this contains the last revision you committed, plus your local edits.
    • foobar.c.r18 — this contains the last revision you committed.
    • foobar.c.r22 — this contains the current revision of the file, pulled from the repository.

Now, you must resolve the state of conflict. How you do this depends on what client version you are running.

Resolving in Subversion 1.4

You must place your file into a desired state, and then run the resolved subcommand. Your basic options are:

  • Copy one of the temporary files onto the actual file. For our foobar.c example,
    • To discard your local changes and accept your teammates' changes, 
      cp foobar.c.r22 foobar.c
    • To discard your teammates' changes and use only your local changes, 
      cp foobar.c.r18 foobar.c
    • To discard all changes (local and teammates) and just start over, 
      svn revert foobar.c
      You will no longer need to run svn resolved if you use this option.
  • Hand-merge the changes by editing foobar.c, including removing all conflict markers.

Now, tell Subversion you have put foobar.c in an acceptable state: 

svn resolved foobar.c

This will automatically delete the temporary files.

Resolving in Subversion 1.5

Subversion 1.5 has replaced the resolved subcommand with resolve. Your options are essentially the same as in Subversion 1.4, but the resolve subcommand can do some of the work for you. Still using the foobar.c example:

  • To discard your local changes and accept your teammates' changes, 
    svn resolve --accept theirs-full foobar.c
  • To discard your teammates' changes and use only your local changes, 
    svn resolve --accept mine-full foobar.c
  • To discard all changes (local and teammates) and just start over, 
    svn revert foobar.c
  • Hand-merge the changes by editing foobar.c, including removing all conflict markers, and then run 
    svn resolve --accept working foobar.c

Committing Local Changes

Once you have brought your working copy up to date, you can commit your changes with the commit subcommand. Be sure to include a log message with the -m option, or else your default editor will be opened for you to write one. 

svn commit -m "Some useful log message"

Reviewing Commit Logs

You can view the commit log message history with log subcommand.

Getting Line-By-Line Author and Revision

Subversion provides a very powerful subcommand, blame, that shows you, line-by-line, what author is responsible for adding or most recently editing the line, and in what revision that line was added or edited. 

svn blame foobar.c

Undoing Committed Changes

Undoing a Change from a Previous Revision

Sometimes you might want to undo a committed change to the repository. Unfortunately there is no pure "undo" in Subversion, because Subversion is designed to track and maintain every change made to the repository. The best you can do is to make sure the change is corrected in the HEAD revision.

As an example, consider a file foobar.c, for which an undesired change was committed at revision 22. By the time you realize it, the repository is up to revision 30, and now you want to undo the change that was made at revision 22. You might be tempted checkout or update your working copy to the revision before the regretted changed occurred: 

svn checkout -r 21 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/myproj/trunk/
svn update -r 21 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/myproj/trunk/

But this will not work, because Subversion will not allow you to commit this older revision when a newer revision exists in the repository.

The answer is instead to perform a reverse merge. (The merge subcommand is covered here). You want to get the delta (changes) from revision 22 back to revision 21—this delta would be a description of the "undo"—and apply to a current working copy (i.e. HEAD revision). 

svn update
svn merge -r 22:21 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/myproj/trunk/
  # or you could use
svn merge -c -22 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/myproj/trunk/

Note that this compares the entire tree, so if numerous changes occurred from revision 21 to revision 22, you may want to make sure those do not get reversed. Now is a good time to use svn status and svn diff to make sure you got what you wanted.

Once you have confirmed the undo operation, just commit your changes with svn commit.

Resurrecting a Deleted File

If you deleted a file in a previous revision and want to "undelete" it, you cannot undo that committed change. The best you can do is resurrect the file so that it exists again in the HEAD revision. This is accomplished with the copy subcommand, by copying the file from a previous revision into your working copy, and then committing to the repository.

For example, if you deleted foobar.c in revision 23: 

svn copy -r 23 svn+ssh://jdoe@svn.ece.msstate.edu/home/jdoe/repos/myproj/trunk/foobar.c ./foobar.c
svn commit -m "Resurrected foobar.c from revision 23, /myproj/trunk/foobar.c."

Keyword Substitution

You might find it useful to see information such as author and modified date directly in your source code files. This can be a maintenance nightmare, as it depends on individuals to update the information as they edit the files. Subversion provides some automated support for this using keyword substitution.

Available Keywords

The following keywords are currently supported by Subversion. Most of them have aliases that perform the exact same substitution, but with a different form of the keyword.

  • Date — displays the date and time (in local time) of the last change to the file in the repository. Alias: LastChangedDate
  • Revision — displays the global revision number at which the file was last changed. Aliases: LastChangedRevision and Rev.
  • Author — displays the username of the last user who changed the file in the repository. Alias: LastChangedBy
  • HeadURL — displays the URL to the head latest version of the file. Alias: URL
  • Id — displays a single string containing the filename, revision, last changed date and time (UTC), and author all combined.

Keyword Formats

You can place keywords wherever you like in your source file, but it is probably best to put them near the top.

The simplest form for entering keywords is: 

$Rev$
$Author$
$Date$

which will expand to something like: 

$Revision: 2341 $
$Author: bully $
$Date: 2006-11-02 12:57:54 -0600 (Thu, 02 Nov 2006) $

You could also add comments to the end, such as: 

$Revision$:  Revision of last commit
$Author$:    Author of last commit
$Date$:      Date of last commit

But note what would happen during substitution: 

$Revision: 2341 $:  Revision of last commit
$Author: bully $:    Author of last commit
$Date: 2006-11-02 12:57:54 -0600 (Thu, 02 Nov 2006) $:      Date of last commit

In order to preserve your spacing, append :: to the end of the keyword. For example: 

$Revision::                                                   $: Revision number
$Author::                                                     $: was committed by
$Date::                                                       $: on this date

This will be transformed into: 

$Revision:: 2341                                              $: Revision number
$Author:: bully                                               $: was committed by
$Date:: 2006-11-02 12:57:54 -0600 (Thu, 02 Nov 2006)          $: on this date

Some important things to note:

  • Make sure these lines are "commented out" in your source files
  • Don't edit these lines once they're entered; Subversion will manage them
  • Each file individually is updated only when it is changed in the repository, which usually occurs by making local changes and then committing them
  • These lines should not lead to a state of conflict on svn update, but they will show up in svn diff

Activating Keywords

Keyword substitution will not happen automatically. Each one must be activated by setting the svn:keywords property on every file that needs substitution to take place.

For example, to activate keyword substitution for Revision, Author, and Date on the file foobar.c, run the following command: 

svn propset svn:keywords "Revision Author Date" foobar.c

Additionally, you can edit the property in your default editor using 

svn propedit svn:keywords foobar.c

To see the property's current value, 

svn propget svn:keywords foobar.c

To delete the property, 

svn propdel svn:keywords foobar.c

See Also

External Links

Retrieved from "http://www.ece.msstate.edu/wiki/index.php/Subversion_Basic_Use"