LINUX GAZETTE EDITOR'S GUIDE TO SUBVERSION 2003-02-09 Sluggo Updated 8 Jul 2006 Ben Subversion is a version control system similar to CVS but with several advanced features. The definitive background, tutorial and reference is the Subversion book, available online at: http://svnbook.red-bean.com/ Subversion's home page is: http://subversion.tigris.org/ ============================================================================== CLIENT INSTALLATION - Email your SSH public key (DSA is preferred) to editor@linuxgazette.net; it will be added to the staff (i.e., 'gazette') account. If you don't have an SSH key, create one by running 'ssh-keygen -t dsa' on your system; the file you need to send will be located in ~/.ssh and will be called 'id_dsa.pub' or 'id_rsa.pub'. - Install the "subversion" package in your Linux distribution (preferred), or compile it from source (http://subversion.tigris.org/). - Set this environment variable in your ~/.bash_profile: export SVN_SSH='ssh -l gazette' - IMPORTANT: For those getting an account of their own - i.e., other than 'gazette' - be sure to set the umask on your new account to '002' (this is done in your ~/.bash_profile on the LG server.) If you don't, it'll generate ugly error messages for everybody else and require hunting down the offending files in $REPOSITORY/db. - Make sure you have a relatively fast network connection - the download is going to be over 200MB - and run the following command: svn checkout svn+ssh://genetikayos.com/var/svn/linuxgazette.net This will create the local directory structure on your system; unless you specify an optional target directory, it will be located in the same place as the source directory on the repository machine (i.e., '/var/svn/linuxgazette.net'.) Note that $LG (or $LG_ROOT) in all further documentation refers to '/var/svn/linuxgazette.net' from the above example, or wherever your working copy lives if you've placed it elsewhere. - Copy $LG/doc/lgrc to ~/.lgrc and customize it for your system; then, source it whenever you run a shell by adding source ${HOME}/.lgrc to your ~/.bashrc (or, if you run a shell other than Bash, to whatever that shell's equivalent of the per-console rc file happens to be.) - If you want to generate finished files for HTML preview, or to upload those files to linuxgazette.net, you need to create a destination directory (whatever you've specified as $LG_WWW in ~/.lgrc). ============================================================================== BASIC LG SUBVERSION TUTORIAL Repository: the central database of the LG files tracked by SVN. Sandbox (working copy): your local copy of these files. Every directory managed by Subversion has a .svn/ subdirectory; this is equivalent to CVS's CVS/ directory. Unlike CVS, Subversion keeps a second copy of every file in this directory. This allows it to do some operations without accessing the server, but it also means your sandbox will take up twice as much disk space as the source files alone require. The Subversion book has a good tutorial of the commands, and also has an appendix for CVS users; I suggest creating a local copy of that tutorial on your machine and referring to it often until you've memorized the few necessary commands. Use the "svn help" command as a good reminder of the basic syntax. You're welcome to create a $LG/p/my_username/ directory and use it to experiment with Subversion. (p = personal) That's also where you'll keep your scratch files if any. Just keep the total size of your scratch files small, and remember to delete them from the repository when no longer needed. Everyone has permission to read/write your scratch files, so don't put any love letters there. You can also tell SVN to ignore these files by using the 'svn propedit svn:ignore ' command, which allows you to enter the filenames and subdirectories (wildcards are allowed) to be ignored in a given directory; that way, the 'svn status' command will not list these as unknown ('?'), and they will not be uploaded to the repository. We are not using "tags" and "branches". If you need to make a private branch, copy the required directory into your scratch directory and tell SVN to ignore it, as above. CVS users: Subversion can move directories just like files, while preserving their history. It has lazy copy (copy-on-write), so "svn cp big_tree dest" does not waste time or bandwidth. ============================================================================== SUBVERSION TROUBLESHOOTING If you get an error like this or an access error: % svn update svn: Couldn't find a repository svn: No repository found in 'svn+ssh://genetikayos.com/var/svn/linuxgazette.net' svn: Berkeley DB error svn: Berkeley DB error while opening environment for filesystem /var/svn/linuxgazette.net/db: DB_RUNRECOVERY: Fatal error, run database recovery Ssh YOU@linuxgazette.net (if you're a member of group 'lgang'; otherwise, ask a staffer) and do: - svnadmin recover /var/svn/linuxgazette.net - chmod g+w -R /var/svn/linuxgazette.net See chapter 5 ("Repository Recovery") in the Subversion book for more info. If you really, *really* hose a subdirectory - say, by deleting '.svn' or something similarly awful - then delete it ('rm', not 'svn rm') from the SVN tree and run 'svn revert ' from its parent directory. Note that this will lose any of the work you've done, so copy any changed files out of that directory and move them back in after 'svn status' shows that everything is back to normal. If you get in *really* bad trouble, email the editor (Ben), who has made all the stupid mistakes^W^W^W^W^Wa lot of experience with SVN and knows where to get the right chainsaw. ============================================================================== FRONT ENDS 'rapidsvn' is a graphical front end to Subversion. http://rapidsvn.tigris.org/ # vim: sw=4 ts=4 expandtab ai