If you maintain many branches in your favorite version control system it is essential understand which branch for which indented.

In SVN you can put README on same level as trunk/branches/features dirs. How about DVCS?

You can maintain ChangeLog. But with this approach it is hard get breif view that done in all branches (if you maintain different long lived releases changelogs between them they can be slightly different).

In open source project info about branches usually can be found on project wiki, so stored separately from VCS. I think this is bad thing. When you clone project you also need aceess to wikis.


I just try to give branches descriptive names. I also try not to have so many of them that I can't remember what they're for.

A good descriptive name is probably enough. I use slashes to categorize branches. e.g.


btw, in Git, if you find yourself having to switch between lots of unrelated tasks it might be better to stash your changes, instead of creating a branch for each. When you stash you can also provide a description of what you're working on:

git stash save "trying out this thing..."

I think any solution that relies on extra-scm registration of each branch is sub-optimal. I've worked with wiki pages and READMEs for this purpose in the past, and having to update them becomes a pain. Git branches are usually short-lived, anyway. So there's not much point of cataloging them.

  • Descriptive names are good for feature branches. But fail if branches used for custom product versions or different product versions. – gavenkoa Jul 10 '11 at 12:31

In git, you can use git notes for this purpose, but it is not really elegant:

In your branch do git notes add -m "this branch is for blah blah"

Then write a post-commit in your repo with the following:

git notes show HEAD~1
git notes copy HEAD~1 HEAD
git notes remove HEAD~1

Use git notes show to see what the branch is for.

Note that note can be pushed to remote repo like any ref, but as I said earlier, this is not elegant, but works, and this is what I use.

Also have a look at this answer to a similar question ( for git ) - https://stackoverflow.com/questions/4750845/how-do-you-annotate-a-branch/4755244#4755244 That answer mentions using the config for storing such info, which would not be propagated to remote repos on push etc. so this may not be what you are looking at.

  • Interesting approach. But seems my boss can not use this techniques for reading stored info. It can read only email/text files. – gavenkoa Jul 10 '11 at 12:35

every branch important enough to to get pushed to our central repository is expected (but not currently required, by fiat of hg update_hooks) to have a corresponding version in our issue tracker. Most branches have simple, but descriptive names, but the definitive authority on what the branch is for comes from the set of issues set to be fixed in the version with the same name as the branch.

  • Nice, instead wikis use BTS. It is possible automatically get list of all branches with descriptions in single text file, so newcomers to project don't need every time go to BTS or VCS? – gavenkoa Jul 10 '11 at 12:20
  • Do you have special tag naming conventions or separate field in BTS for marking and querying branches in BTS? – gavenkoa Jul 10 '11 at 12:22
  • 1
    well, we use a fairly formal version number for actual release versions (, etc) and all other versions have corresponding feature branches in vc. The names of those branches are usually pretty descriptive (awesome.widget.support, fix.awesome.widet.support, etc), and if anything is really more involved than a few user stories, there will often be a "Task" type ticket that describes the overall plan for the feature, and if it's a formal requirement, probably a wiki page; but the wiki normally is less authoritative than BTS. – SingleNegationElimination Jul 10 '11 at 17:14

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.