Today has seen some major Subversion usage messups that indicate a general unfamiliarity with the tool and/or proper use of revision control. Below is a quick guide to everyday Subversion use taken from the MPlayer project. The project-specific parts do of course not apply to us, but the general guidelines do. Maybe we should hold a quick seminar and get everybody up to speed regarding proper Subversion usage. I can do that if there is interest. Diego About Subversion write access: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before everything else, you should know how to use Subversion properly. Luckily Subversion comes with excellent documentation. svn help shows you the available subcommands, svn help <command> shows information about the subcommand <command>. The most comprehensive manual is the book "Version Control with Subversion" by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. It can be viewed online at http://svnbook.org/ For more information about the Subversion project, visit http://subversion.tigris.org/ Consult these resources whenever you have problems, they are quite exhaustive. What follows now is a basic introduction to Subversion and some MPlayer-specific guidelines. Read it at least once, if you are granted commit privileges to the MPlayer project you are expected to be familiar with these rules. I. BASICS: ========== 0. Get Subversion: The MPlayer project server runs Subversion 1.5. For optimal compatibility you should use version 1.5 or later. 1. Checking out the source tree: svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ <target> This will put the MPlayer sources into the directory <target>. 2. Updating the source tree to the latest revision: svn update pulls in the latest changes from the repository to your working directory. 3. Adding/removing files/directories: svn add <filename/dirname> svn delete <filename/dirname> Subversion needs to get notified of all changes you make to your working directory. 4. Showing modifications: svn diff <filename(s)> will show all local modifications in your working directory as unified diff. 5. Inspecting the changelog: svn log <filename(s)> You may also find viewvc, a web frontend for Subversion, helpful. It's often more comfortable than using 'svn log' and 'svn diff'. Find it here: http://svn.mplayerhq.hu/mplayer/trunk/ 6. Checking source tree status: svn status detects all the changes you made and lists what actions will be taken in case of a commit (additions, modifications, deletions, etc.). 7. Committing: svn update Run 'svn update' before committing to make sure there were no changes to the files you worked on in the meantime. Afterwards look at the output of svn diff <filename(s)> to doublecheck your changes before committing to avoid trouble later on. All experienced developers do this on each and every commit, no matter how small. Every one of them has been saved from looking like a fool by this many times. It's very easy for stray debug output or cosmetic modifications to slip in, please avoid problems through this extra level of scrutiny. For cosmetics-only commits you should get (almost) empty output from svn diff -x -uwb <filename(s)> Also check the output of svn status to make sure you did not forget to 'svn add' some files (they will be marked with '?'). Once you have made sure everything is fine svn commit <filename(s)> propagates your stuff to the repository. If you have made several independent changes, commit them separately, not at the same time. When prompted for a password, type the password you got assigned by the project admins. By default, Subversion caches all authentication tokens. This behavior can be disabled by setting both 'store-passwords' and 'store-auth-creds' to "no" in ~/.subversion/config. You might need to remove previous cache files, which are located in ~/.subversion/auth, by hand. You will be prompted for a log message in an editor, which is either specified by --editor-cmd on the command line, set in your personal configuration file (~/.subversion/config) or set by one of the following environment variables: SVN_EDITOR, VISUAL or EDITOR. Log messages should be concise but descriptive. Explain why you made a change, what you did will be obvious from the changes themselves most of the time. Saying just "bug fix" or "10l" is bad. Remember that people of varying skill levels look at and educate themselves while reading through your code. Don't include filenames in log messages, Subversion provides that information. 8. Renaming/moving/copying files or contents of files: svn move/copy <source> <destination> svn commit <source> <destination> Do not move, rename or copy files of which you are not the maintainer without discussing it on the mplayer-dev-eng mailing list first! Never copy or move a file by using 'svn delete' and 'svn add'. Always use 'svn move' or 'svn copy' instead in order to preserve history and minimize the size of diffs. To split a file, use 'svn copy' and remove the unneeded lines from each file. Don't do a lot of cut'n'paste from one file to another without a very good reason and discuss it on the mplayer-dev-eng mailing list first. It will make those changes hard to trace. Such actions are useless and treated as cosmetics in 99% of cases, so try to avoid them. 9. Reverting broken commits There are 2 ways to reverse a change, they differ significantly in what they do to the repository. The recommit old method: svn merge svn ci <file> This simply changes the file(s) back to their old version locally and then the change is committed as if it were a new change. The svn copy method svn rm <file> svn cp -r<good revision> svn://svn.mplayerhq.hu/mplayer/trunk/[<path>/]<file> <file> svn ci <file> This simply removes the file and then copies the last good version with its history over it. This method can only be used to revert the n last commits but not to revert a bad commit in the middle of its history. Neither method will change the history, checking out an old version will always return exactly that revision with all its bugs and features. The difference is that with the svn copy method the broken commit will not be part of the directly visible history of the revisions after the reversal So if the change was completely broken like reindenting a file against the maintainers decision, or a change which mixed functional and cosmetic changes then it is better if it is not part of the visible history as it would make it hard to read, review and would also break svn annotate. For the example of a change which mixed functional and cosmetic parts they should of course be committed again after the reversal but separately, so one change with the functional stuff and one with the cosmetics. OTOH if the change which you want to reverse was simply buggy but not totally broken then it should be reversed with svn merge as otherwise the fact that the change was bad would be hidden. One method to decide which reversal method is best is to ask yourself if there is any value in seeing the whole bad change and its removal in SVN vs. just seeing a comment that says what has been reversed while the actual change does not clutter the immediately visible history and svn annotate. If you are even just slightly uncertain how to revert something then ask on the mplayer-dev-eng mailing list. 10. Reverting local changes svn revert <filename(s)> In case you made a lot of local changes to a file and want to start over with a fresh checkout of that file, you can use 'svn revert <filename(s)>'. NOTE: This has nothing to do with reverting changes on the Subversion server! It only reverts changes that were not committed yet. If you need to revert a broken commit, see 9. 11. Changing commit messages svn propedit svn:log --revprop -r <revision> If your commit message is too short or not explanatory enough, you can edit it afterwards with 'svn propedit'.