3

Possible Duplicates:
How do you annotate a branch?
Branch descriptions in git

I have a repo with lots of branches. Maybe 12 or so, and they won't be merged into master anytime soon.

Is there a way to document the purpose of each branch within git?

The thing I seek is to a branch what a commit message is to a commit.

I don't think tags are what I want, because tags don't follow the HEAD as I add more commits to a branch.

I could write a plaintext file listing the state of each branch with some notes, but its not obvious which branch the text file would go in.

To clarify, I do name my branches. But I would want to be able to have a description too. So for example I would want to write for branch RTPhase:

This branch has added features to support real-time analysis of curvature and phase. As a trade off it runs more slowly than other branches because it uses functions like calculate mean curvature that haven't been optimized for speed.

Community
  • 1
  • 1
AndyL
  • 14,302
  • 14
  • 43
  • 70
  • Are you using named branches? – Matt Ball May 27 '11 at 19:28
  • Yes. I used name branches. But the names tend to be somewhat short, like, 10 characters or so, because otherwise its annoying to switch between things. – AndyL May 27 '11 at 19:30
  • 1
    Try http://stackoverflow.com/questions/2108405/branch-descriptions-in-git – John Flatness May 27 '11 at 19:35
  • An interesting workaround is described here: http://stackoverflow.com/questions/4750845/how-do-you-annotate-a-branch (however, the notes cannot be pushed to remotes) – Aasmund Eldhuset May 27 '11 at 19:35
  • 1
    What you really want is autocompletion for your shell, so you can start typing a branch name, hit tab, and have the shell fill in the rest for you. – Wayne Conrad May 27 '11 at 21:58

3 Answers3

3

The answer I'm coming to about this is to devise a convention that I can hew to rigidly.

My master "release" branch is called "master". My "hotfix" branch (for fixes live in production) is called "hotfix". My branch for development on the next release is called "dev".

Then I make any branches off of those branches carry the name. So a feature branch for something I'm working on here to do with maps is called "dev/maps". I have a survey feature I'm adding in a branch "dev/survey".

If I had a hotfix that was going to take any real time to do, I'd probably branch into "hotfix/short-description-of-branch".

The slash doesn't have any syntactic value in a branch name, it's just text, but I use it to imply "inside-ness".

Dan Ray
  • 21,623
  • 6
  • 63
  • 87
1

You might not like it, but just for fun ( atleast for me :) the below is what I would do:

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:

#!/bin/sh
git notes show HEAD~1
git notes copy HEAD~1 HEAD

Additionally add a git notes remove HEAD~1

Use git notes show to see what the branch is for. Tadaaa! :)

manojlds
  • 290,304
  • 63
  • 469
  • 417
  • 2
    Cool trick, but it doesn't sync easily with remote branches: http://progit.org/2010/08/25/notes.html – AndyL May 27 '11 at 21:53
1

Without knowing what you are doing, you might find a different workflow with a workflow support tool easier to use. For example: http://nvie.com/posts/a-successful-git-branching-model/ and the associated gitflow support tool.

It doesn't have branch descriptions per-se, but perhaps if you added that feature it would be accepted.

Seth Robertson
  • 30,608
  • 7
  • 64
  • 57