This page is intended to explain enough about Subversion to work with the Debathena repository. For more information on Subversion, see O'Reillys "Version Control with Subversion", available at [http://svnbook.red-bean.com/], or though the MIT Libraries' subscription to [http://libraries.mit.edu/get/safari Safari (Touchstone authentication required)] [[PageOutline]] == Getting started == Normally, you would use the Subversion URL `svn+ssh://svn.mit.edu/athena/trunk` to work with Subversion. However, this requires write access to the repository. If you don't have write access, you'll only be able to check out the code, not commit anything, and you'd use the URL `svn://debathena.mit.edu/athena/trunk` instead. Changes in subversion are identified with revision numbers (e.g. r12345). This revision number applies to the entire repository, even though the actual change likely only affected a few files. == Initial checkout == Identify a location in your filesystem for your working copy of the source, and change to that directory. Then, checkout the source with the following command: `svn co svn+ssh://svn.mit.edu/athena/trunk athena`. This will create a directory called `athena` in the current directory, with the Athena source tree inside that directory. That directory is called a *working copy*. == Getting an update from the server == Before making changes, you'll want to ensure you have the latest copy of the code. `svn update` will get you the latest copy of the code. {{{ joeuser@athena:~$ svn update A foo.c U bar.c D baz.c }}} In this example, foo.c is a new file, bar.c was changed ("updated"), and baz.c was deleted. It's possible you'll encounter conflicts at some point, but that will be covered later. == Making changes == Most text editors are aware of when you're editing files inside a working copy. Emacs, for example, won't create "twiddle files" (`filename~`) because it assumes Subversion will keep track of your changes. === Adding or removing files === If you create new files or directories, you'll need to ensure Subversion is aware of them. You can wait until just prior to the commit to do this, or you can do it as you go. To add files or directories use `svn add`: `svn add foo.pl`[[BR]] `svn add *.c`[[BR]] `svn add subdir`[[BR]] To remove files previously added, use `svn del`: `svn dell foo.pl`[[BR]] `svn del *.c`[[BR]] `svn del subdir`[[BR]] == Reviewing your changes == To view information about what files have been changed, use `svn status`. By default, it will display status on the current location in the repository, or you can specify a directory or file, or with no arguments *Tip:* Make sure you're in the right directory when you run this command. For example, if you're working on package `foo`, but you're actually in `foo/bar`, it might not give an accurate listing of your changes to be committed. Example: {{{ joeuser@athena:~$ svn status A foo.c M bar.c D quux.c ? subdir ! baz.c }}} In this example, bar.c has been changed and will be committed. foo.c is a new file, which has been added with `svn add`, and quux.c has been deleted with `svn del`. The directory `subdir` exists in the filesystem, but is not under version control. If it's part of the package, you'll need to add it with `svn add`. The file `baz.c` should exist, but doesn't. If you delete a file with `rm`, you'll also need to `svn del` the file so Subversion knows it's gone. Additional information about the output format of `svn status` is available in the documentation, or with `svn help status`. === Diffs === If you want actual diffs, you can use the `svn diff` command. Like `svn status`, it can take optional file specifiers, or display all diffs. == Reverting changes == If you realize that you didn't want to make changes, you can revert a file's changes. Without any arguments, `svn revert` will revert your entire working copy, and won't ask for confirmation, so use it with care. `svn revert foo.c` == Committing your Changes == Before committing, make sure your working copy is up to date with `svn update`. You commit your changes with `svn commit`. You can specify files to commit, or by default it will commit everything in the current working directory and subdirectories. It's best to run `svn status` ahead of time to verify what will be changed. You'll also want to specify a commit message with "-m". Commit messages should be descriptive, but concise. Don't mention what files have changed, the commit log will tell other users that. Instead, say what you actually did. Example: `svn commit -m 'Fixed a string-handling bug in bar.c'` If you are in the root directory of a package, and have added a new Changelog entry to `debian/changelog`, you can leave the commit message blank, and the Subversion server will use the contents of the new Changelog entry as the commit message: `svn commit -m ''`[[BR]] ^(That's two single-quotes, i.e. an empty string)^ === Reverting a commit === If you want to revert a commit that you've already made, you can't use `svn revert`. Instead, you need to merge the changes back in to the current working copy, and then re-commit it. Example: You've just committed change r12345. To revert it in your working copy: `svn merge -r 12345:12344 .` (don't forget the trailing period so Subversion knows to operate on the current working directory) This will reverse-merge the changes from 12344 (what it looked like before your commit) into the current working copy. You'll then need to commit the changes: `svn commit -m 'Reverted r12345'`