Docs/Drafts/SVN Tutorial

= Subversion =

Note to Red Hat employees: the content in the following sections was copied with permission.

Subversion (SVN) is a version control system. It replaces CVS and, like its forebear, keeps track of changes made to books. The Subversion project is hosted by Tigris.org and a command reference can be downloaded in PostScript format from the site. (NB: Evince, the PDF and PostScript file viewer included with Fedora can display PostScript files.)

Configuring an SVN Editor
Add the following line to your  file to see a list of files that will be committed during an SVN commit:

export SVN_EDITOR=/bin/vi

After configuring the  variable, running the   command displays list of files that have been modified. This is useful if you accidentally modified a file that you do not want to commit back into SVN. Running the  command does display which files have changed, that is, the files that are being committed back into SVN.

Commonly used Terms
Familiarize yourself with the following terms before proceeding:


 * import: import a local copy of a book into SVN. If you create a book using the publican  command, you need to import this copy onto the server. Running the   command copies your local copy onto the SVN server.


 * checkout: checkout a book from an SVN server. This copies an existing book from an SVN server onto your local machine. You only need to checkout a book once. Periodically run the  command to update your local copy with changes other people have made.


 * commit: commit your changes back into SVN. This updates the server copy with the changes you have made. Run the  command to update the server copy with your changes.

= SVN Basics =

Below are the most basic SVN functions and commands you need to learn:

Getting Help

 * Run the  command to display a list of SVN subcommands.
 * Run the  command, where   is an SVN subcommand, to display the help for that subcommand. For example, running the   command displays help for the   command.

Importing a Book
If you created a new book using the publican  command, you need to import your local copy into an SVN repository. Run the following command to add your local copy to the server:

svn import /local/path/to/My_New_Book https://path/to/svn/repository/My_New_Book

The  command imported your local copy into SVN, but has not marked your local copy as a checked-out version of the newly created repository. To resolve this, first backup your local copy:

mv My_New_Book My_New_Book.backup

Check the book out using the svn co command:

svn co https://path/to/svn/repository/My_New_Book

When you are happy that the book has been checked-out correctly, remove the backup copy. Be very careful with this command:

rm /local/path/to/My_New_Book.backup -rf

Checkout a Book
You only need to checkout a book once. Checking out a book will store a local copy on your machine. Change into the directory where you want to store a local copy of the book, and run the following command:

svn co https://path/to/svn/repository/My_New_Book

Checkout a Book Branch
Run the following command to checkout a book branch:

svn co -N https://path/to/svn/repository/My_New_Book/path/to/branch

This command only checkouts the book specified by. The  option is non-recursive, so only the directory or branch specified is downloaded, instead of the entire book.

Checkout a Book Revision
Run the  command to display the revision history. The following is an example revision entry:

r1785 | user@something.com | 2007-12-14 12:00:09 +1000 (Fri, 14 Dec 2007) | 2 lines rename title logo in text

is the revision number. Run the following command to checkout a specific revision of a book:

svn co -r x https://path/to/svn/repository/My_New_Book

Replace  with a revision number, for example,. Run the  command for a full list of options.

Updating Files
To update your local copy with changes other people may have made, change into the root of the book directory, and run the following command:

svn up

Run this command every one to two days. The latest versions of all files in the book are downloaded into your local copy.

Adding Files
To add a file to a book, create the file in your local copy, and run the following command:

svn add file-to-add

After adding the file, you must commit the add to copy it to the server:

svn ci

Alternatively, run the following command:

svn ci -m'enter a description here' file-to-add

Committing Files
After modifying files in your local version of a book, commit them to save the changes on the SVN server. Run the following command in the root of the book directory:

svn ci

If you configured your  with , vim opens and a list of modified files appears. Press the  key, and then enter a description of the changes you made. If you edited a file in line with a Bugzilla number, be sure to include the Bugzilla number in the description. Once you have entered a description, press the  key, type , and press the   key. Your changes are then committed to SVN.

Alternatively, run the following command to commit changes back into SVN; however, a list of modified files is not displayed:

svn ci -m'enter a description here'

Removing Files
If a file is no longer needed in the book, use the following command to remove it from your local version, and from the server:

svn remove file-to-remove

Even though the file is removed from current version of the book, an archived copy is still kept on the server and can be retrieved at any time. After removing the file, you must commit the removal to remove the file from the server:

svn ci

Alternatively, run the following command:

svn ci -m'enter a description here' file-to-remove

Viewing the Revision History
To view a list of past committs, and depending on the comments, what was changed, run the following command in the root directory of a book:

svn log

Moving Books in SVN
If you imported your book to the wrong URL, or would like to move it, use the  command:

svn move https://path/to/old/Book_Name https://path/to/new/Book_Name

The first URL is the old location. The second URL is the location you want to move the book to.

Removing a Book from SVN
You should not have to remove a book from SVN; however, use the  command if required. Make sure the URL is correct before running this command:

svn remove https://path/to/the/book/you/want/to/remove/Book_Name

Changing the commit location of a book for SVN
There may be a time when you need to change the location that a book will commit to in SVN. An example case would be if you checked out a book anonymously but then wish to commit changes to the book after having gained write access to that repository. In order to do this you will need to undertake the following steps:

You will first need to navigate to the root folder of the checked out book. For each folder that exists in the book that has been checked out, will also exist a hidden folder called .svn. Within this folder will be a read-only file called entries.

Opening the entries file with your chosen text editor, first save another copy of the file and then edit the two web addresses near the top of the file.

This example demonstrates changing the SVN path from an anonymous repository with only checkout rights, to the commit repository for the same book.

Before: 8 dir 18472 https://anonsvn.labs.jboss.com/path/to/project/documentation https://anonsvn.labs.jboss.com After: 8 dir 18472 https://svn.labs.jboss.com/path/to/project/documentation https://svn.labs.jboss.com

Once you have edited the two lines (in the example this is removing anon from the path), save the new file. Next you will need to delete the existing entries file and rename the file you just created to be called entries, with read-only access.As stated before, the changing of the entries file will need to be done for each folder that occurs in the book.

After updating all the required files, navigate back to the root folder of the book and run the following command:

svn cleanup

The  command will re-curse through the book and remove the log files. This is done so that there is no reference left to the old repository from where you checked out the book to begin with.

Run the  command to commit your book to the new repository address.

= Status of Files =

Sometimes it is necessary to view the status of a file in an SVN book. To view the status of a file, use the following command:

svn status filename

To view the SVN status of all files in an book, change into the  directory, and run the following command:

svn status

The following is a list of common statuses. For a full list, run the  command:


 * A the file has been added. Run the  command to commit the file to the server. If you create a new file and then run the   command, and then the   command, the file has an   status.


 * ? the file is not under version control. This is common for.


 * C conflicting. A file you have modified is conflicting directly with changes someone else has made prior to checking the book back into SVN.