Subversion
From BroWiki
Contents
|
Layout of the Repository
- trunk/
- Current development version; maintained by Vern.
- bro/
- Source code (public)
- bro-web/
- Web pages for http://www.bro-ids.org
- devel-traces/
- Traces for development
- local/
- Local policy files
- testing/
- Testsuite
- releases/
- Bro releases; maintained by Brian.
- branches/
- Developer branches (partially public)
- tags/
- Global tags.
Public Access
Selected sub-paths of the repository are available for public read-only access. Currently, these are:
| Path | Logs | Description |
|---|---|---|
| http://svn.icir.org/bro/trunk/bro/ | RSS feed | Current development version and base for releases. |
| http://svn.icir.org/bro/branches/robin/work | RSS feed | Robin's primary development branch. |
The repository root for public access is http://svn.icir.org/bro. For example, here's how to check out the trunk:
svn checkout http://svn.icir.org/bro/trunk/bro
Developer Access
Developers with personal Subversion accounts can access to the whole repository. All developers have write-access to branches/* and tags/*. Write-access to the other areas is restricted.
For developers, the repository root is svn+ssh://svn.icir.org/bro. So, again, here's how to check out the trunk if you have an account:
svn checkout svn+ssh://svn.icir.org/bro/trunk/bro
If you want the test-suite as well, checkout:
svn checkout svn+ssh://svn.icir.org/bro/trunk/testing
(Note that the test-suite is not publically available because it contains private data.)
Create a branch from the trunk
It is suggested to first make a personal subdirectory in branches and then create the branch there:
svn mkdir svn+ssh://svn.icir.org/bro/branches/<login> svn copy svn+ssh://svn.icir.org/bro/trunk/bro svn+ssh://svn.icir.org/bro/branches/<login>/my-branch</tt>
Then you can check the branch out:
svn checkout svn+ssh://svn.icir.org/bro/branches/<login>/my-branch</tt>.
How to get your features into the trunk
- Create a personal branch and implement your feature there.
- Create a file called CHANGES.features in the top-level directory of your branch. (If you branch from trunk instead of trunk/bro then in the bro subdirectory of your branch.)
- Create an entry for your feature in your CHANGES.features. An entry needs to contain:
- A description of the change, preferably in a form suitable for Bro's CHANGES file.
- A clear indication whether you consider the feature to be stable for merging into the trunk.
- A list of all revision numbers related to your change in the form "$Revisions: r42, r45-r48, r50". Note that this is parsed automatically: you need to use the "$Revisions" keyword, put the whole list into a single line, and prefix each revision with "r". Take care to not commit unrelated changes within the same commit action.
Example:
- A new documentation system. Bro is now able to generate full documentation automatically for every aspect of the system. Nothing needs to be written manually by the developers. The resulting book is automatically pushed out to Amazon. Status: Ready to merge. $Revisions: r42, r44-r48, r50
- Wait until Vern picks up your change (if it takes too long, send him a friendly reminder :-). After integrating the change, he will delete the entry in your CHANGES.features. If he did any further tweaks, he'll send you a corresponding diff which you can apply to your branch.
- To help you getting the right revision number into CHANGES.feature, there is a wrapper script for svn, called bro-commit, which determines the next available revision number and inserts it automatically. To use it, insert the place-holder $REV into your CHANGES.features at the location where you want the revision number to appear (i.e., typically at the very end of the $Revisions: line). Then run bro-commit with the arguments you'd normally give to svn commit. The script will replace $REV with the next available revision number and then pass all its arguments on svn commit (it will automatically add CHANGES.features to the list of files to be commited so you can skip that one.).
How to merge the latest features from the trunk into your branch
- Remember the revision number when you created your branch or did the last merge, respectively. You get the current revision number with update (see below how you can find it out afterwards.)
>svn update At revision 21.
- Make sure all the changes in your working-copy are committed.
- Get the current HEAD revision number:
>svn update At revision 42.
- Change into your working-copy and merge in the changes performed on the trunk since your last merge (i.e., the remembered revision number, 21 in this example):
>cd <working-copy>
>svn merge -r 21:42 svn+ssh://svn.icir.org/bro/trunk/bro
- If there are any conflicts, resolve them:
>vi file_with_conflict.cc
>svn resolved file_with_conflict.cc
- Commit the merge:
>svn commit -m "Merged trunk into my branch at revision 42"
- If you don't know when you created the branch, do svn log --stop-on-copy. This flag instructs SVN to stop going back through previous changes once it reaches a point where the tree was copied, such as to create a branch; see the Subversion book. If you've forgotten when you did the last merge, search the output of svn log for a corresponding message. If you've followed the example above, you'll have the revision right there in the log message.
- Instead of using revision numbers, you can also tag the trunk. Again see Subversion book for more information.
- If you're unsure, svn merge has the option --dry-run which does everything except for any actual change.
- If something failed, svn revert will roll the merge back.
- The Subversion book has a full chapter on Branching and Merging.
How to merge features into the trunk (Vern-style :-)
The easiest case: merging-in a single revision
- Create a patch for the change (e.g., r3199) by diffing its revision number against its predecessor:
>cd working/copy/of/branch >svn diff -r 3198:3199 >r3199.diff
- Create a copy of the patch:
>cp r3199.diff r3199.diff.orig
- Tweak the patch as required:
>vi r3199.diff
- Apply the patch to a working-copy of the trunk:
>cd working/copy/of/trunk/bro >patch -p0 <r3199.diff
- Perform further edits as needed.
>vi blah blah blah .... >make
- Capture a diff of the final version. Do this from the SVN base directory so that the filenames match those in the original patch.
>cd top-level >svn diff bro >r3199.diff.final
- Commit the change:
>svn commit bro
- Mail a diff of the tweaks to the feature author:
>interdiff r3199.diff.orig r3199.diff.final | mail -s "Merged r3199 into the trunk" foo@icir.org
- The original author can now apply this patch to his branch and remove the CHANGES.features entry. Or, alternatively, go ahead and commit the changes to the author's branch yourself.
Merging features spread over multiple revisions
The main difference here is that you first need to create a single patch file which contains all of the changes. combinediff helps with this (see "Notes" below on how to automate this). Let's say you want to merge in r3200, r3201, and r3205.
- First create one patch per continuous revision range:
>cd working/copy/of/branch >svn diff -r 3199:3201 >r3200-r3201.diff >svn diff -r 3204:3205 >r3205.diff
- Then combine all of the patches into one cumulative patch (note that combinediff can only work on two patches at a time, so with more diffs this will require multiple steps. Perhaps we should write a script for this which takes a list of revisions and builds a combined patch.)
>combinediff r3200-r3201.diff r3205.diff >combined.diff
- Now proceed as before, i.e., tweak, apply, commit, and mail.
Notes
- svn diff can be done without having a working-copy of the branch lying around by adding the URL of the repository to the command line.
- There's a script make-patches which reads the CHANGES.features in the current directory and automatically builds a cumulative patch for each revision list prefixed with a "$Revisions" keyword, using svn diff and combinediff.
How to mark files as binary to avoid diffs
Some files should really be treated as binary so the addition, removal, or update of such files doesn't trigger enormous diffds. PDF files are an example. Setting the svn:mime-type property of the file to application/octet-stream does the trick:
svn propset svn:mime-type application/octet-stream <files>
