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 ~/.bashrc
file to see a list of files that will be committed during an SVN commit:
export SVN_EDITOR=/bin/vi
After configuring the SVN_EDITOR
variable, running the svn ci
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 svn ci -m "this is a log file"
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
create_book
command, you need to import this copy onto the server. Running thesvn import
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
svn up
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
svn ci
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
svn help
command to display a list of SVN subcommands. - Run the
svn help subcommand
command, wheresubcommand
is an SVN subcommand, to display the help for that subcommand. For example, running thesvn help add
command displays help for thesvn add
command.
Importing a Book
If you created a new book using the publican create_book
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 svn import
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 <command>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 My_New_Book/path/to/branch
. The -N
option is non-recursive, so only the directory or branch specified is downloaded, instead of the entire book.
Checkout a Book Revision
Run the svn log filename
command to display the revision history. The following is an example revision entry:
------------------------------------------------------------------------ r1785 | user@something.comd | 2007-12-14 12:00:09 +1000 (Fri, 14 Dec 2007) | 2 lines rename title logo in text ------------------------------------------------------------------------
r1785
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 x
with a revision number, for example, 1785
. Run the svn help checkout
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.
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 ~/.bashrc
with export SVN_EDITOR=/bin/vi
, vim opens and a list of modified files appears. Press the i
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 Esc
key, type :wq
, and press the Enter
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'