branch description

Hi,

I find it useful to use fairly short names for branches. However, sometimes I would like to have a full sentence to actually describe what the branch is for, without having the peruse the actual commits.

This is both for when I later can't remember why I made a certain branch, or for when people clone and look at a list of branches wondering what the differences are between them.

This information could of course be kept on a web page, but it would be nice to have it in the repo. Is there any such branch annotation command? Ideally I'd like to see a sentence displayed next to the branch name when I use "git-branch". Perhaps, git-branch --info or something.

Steve

Me too.

Like, putting your bug number in the branch name.

The problem is that a branch is just a floating name for a line of development. Its not really a "thing" in the repository like a tag or a commit. You'd need to make some sort of special tag that describes the branch or somesuch.

On Apr 15, 2008, at 1:31 PM, Russ Dill wrote:

No special tags needed. A simple file that I'll call .git/info/ ref_names could be a set of lines that have "<ref>\t<description>", like the following:

refs/heads/master Collection point for all my work refs/heads/ref_names Add descriptions for branches refs/heads/segfault Trying to fix bug #12345

Simple, no tags, new object types or anything. All you have to do is add the bits to git-branch to add, edit, and remove the description alongside the branch itself.

Now if you want to propagate these descriptions when you push and pull, things get a lot more complicated.

~~ Brian

Brian Gernhardt <benji@silverinsanity.com> writes:

Not complicated at all. Put that description in-tree in a known location (say, "help-branch") in-tree and your propagation problem is solved.

And have a scriptlet in $HOME/bin/git-help-branch to grep from that file.

On Tue, Apr 15, 2008 at 12:12:16PM -0700, Junio C Hamano wrote:

It is perhaps a little slow if you want to do things like adding the help text to branch name decorations in log output. Maybe instead of a flat file, you could parallel the ref name hierarchy in a tree? I.e.,

  git checkout help-branch
  echo 'Collection point for all my work' >refs/heads/master
  git commit -a

As a bonus, you don't even need a git-help-branch script:

  git show help-branch:refs/heads/master

And if you have more than one person tweaking the help-branch text, merging will be much less painful.

-Peff

On Tue, Apr 15, 2008 at 03:19:30PM -0400, Jeff King wrote:

It occurred to me that you actually meant "just stick it in a file in your actual work tree", not on a separate branch (for some reason, reading the name "help-branch" made me think you meant a ref).

So that is obviously the very simple solution. But for fun, and because maybe somebody could learn something, here is a script implementing my approach. I dunno if it is worth including in contrib.

-- >8 -- contrib: add git-refinfo

This is a cute hack to show one possible way of storing ref descriptions. It might be useful to somebody. It also serves as a relatively short and simple example of how to script git.

Signed-off-by: Jeff King <peff@peff.net>
---
 contrib/examples/git-refinfo.sh |   87 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 87 insertions(+), 0 deletions(-)
 create mode 100755 contrib/examples/git-refinfo.sh

Jeff King <peff@peff.net> writes:

Another independent approach I was very tempted to suggest was to mimick how "What's cooking" has been maintained over time (in other words, what I describe here is a toolset that has proven to be viable and useful, backed by the real world experience ;-).

All the tools I use for this are stored in my 'todo' branch, and I have a checkout of the 'todo' branch in Meta/ subdirectory.

The core workhorse of this toolset is "Meta/topic.perl" script. It lists topic branches, and shows the list of commits on each branch that are still not integrated in the final integration branch. The script has a built-in assumption of how the topic branches are named, and what integration branches there are (namely, 'master', 'next' and 'pu'), but it should not be too hard if somebody wants to generalize it to have more than two "still cooking" stages and how they are named.

The' topic' script is called by "Meta/WC" script (obviously, that stands for "What's Cooking") that applies a slight formatting of its output. There isn't much to see in this intermediate script.

When I send out a new edition of "What's cooking", I feed the previous edition of the message to "Meta/UWC" ("Update What's Cooking") script.

This script:

 - reads the old edition from its standard input, to remember the commits
   and explanatory text associated with each topic in the previous round;

 - reads from the "Meta/WC" output to learn the commits that currently
   reside in each topic;

 - compares the above two, insert new branches into "[New topics]"
   section, and mark the changed topics.

 - outputs the new edition to the standard output.

Then I can add descriptions for new topics, edit them for the ones whose status have changed.

I do not personally keep any temporary or in-tree copies, because I happen to do all the above in my MUA edit buffer. But if I wanted to, I could use one in-tree file dedicated for it and track it as part of the contents.

On Tue, Apr 15, 2008 at 3:12 PM, Junio C Hamano <gitster@pobox.com> wrote:

Hm, I wasn't sure if an in-tree solution would be appropriate. It's possible, but I didn't really want this branch description to be something I have to deal with when merging.. Ideally though this information _should_ be propagated through a clone, so something in-tree might make sense.

When I posted I thought perhaps there was already a way to do this that I hadn't encountered. Perhaps there could be an in-tree file .gitbranch that is simply a name:description pair, "git-branch --info" (or whatever) could be made to know how to parse that file if it exists.

However I was hoping that the branch description could be made when creating the branch, instead of having to associate it with an actual commit.

I don't know, I'll give it some thought and try to come up with a more concrete proposal.

Steve

On Apr 15, 2008, at 4:53 PM, Stephen Sinclair wrote:

A random thought:

refs/info/heads/help is a pointer to a blob that is full of name- description pairs. Instead of a full ref name it simply keeps the portion for a given subdirectory. On a pull, you can add refs/info/ heads/help:refs/info/remote/origin/help. Each subdirectory of refs gets it's own help blob. You may need to deal with merging on pull, but it keeps the information separate from the commits and still pull/ pushable.

~~ Brian

Junio C Hamano <gitster@pobox.com> writes:

[...]

Please, let's don't repeat Mercurial mistake of placing unversioned information (such as branch names in case of Mercurial, or branches descriptions in this case) in-tree, i.e. version it. Think of what would happen if you reset to the state (or checkout to some branch with the state) which is before some branch was created, or before some branch got description. Mercurial deals with this using "special" not lika in-tree treatment of such a file... I don't think it is a good idea.

I think it wouldb be better to put branches descriptions somewhere outside object repository, be it .git/info/ref_names of .git/config.

On Tue, Apr 15, 2008 at 06:33:48PM -0700, Jakub Narebski wrote:

I think that is a reasonable argument.

But you make a jump in logic here when you make the alternative to put it outside the object repository. Your first point argues against versioning meta-information _along with the rest of the state_, but there's no reason it can't be versioned separately (e.g., in another branch that just has such meta-info).

-Peff

On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:

This got me thinking... It's a little crazy, but: since branch descriptions would essentially just be an extension of the branch name, play basically the same role and have the same requirements for storage, cloning, etc., what about using some syntax in the branch name itself to separate a "short name" and a "long name"..

That is, you could store it as, refs/heads/wip:work_in_progress

and git-branch would report,

wip

while git-branch --long would report the long names,

wip:work_in_progress

or could parse it to something more legible:

wip     "Work in progress"

Of course this would require modification to refspec-related code, which is likely more work than it's worth.. Hm, well just an idea anyways. Probably not a good idea to save meta-data in a filename.

Steve

On Tue, Apr 15, 2008 at 11:28:49PM -0400, Stephen Sinclair wrote:

Why not simply add the text after the sha1 in the refs/heads/branch_name file ? Obviously current and older git code should be checked to know whether they could cope with the extra data without failing...

This would also have the advantage that renaming the branch would not lose the description.

Mike

On Tue, Apr 15, 2008 at 9:33 PM, Jakub Narebski <jnareb@gmail.com> wrote:

I agree that outside the object repository would be better. Propogating branch descriptions doesn't seem all that useful. I wouldn't usually expect to want a branch for the same purpose as the upstream repository and it would seem weird to get a default description of it coming along with the branch. Just like I give my branches my own name, I would expect to have to give them my own description.

On Wednesday 16 April 2008, Matt Graham wrote:

On the contrary, when I clone/pull from some repo, I would very much like to have a copy of its branch description stored locally. Of course, these descriptions should be renamed along with their corresponding branch upon entering my repo. To illustrate: Suppose I clone/pull "refs/heads/foo" from a remote repo "bob". The branch will be stored as "refs/remotes/bob/foo" in my repo. Now, if "refs/heads/foo" on "bob" has a branch description, I would like to have that branch description copied into my repo, but referring to "refs/remotes/bob/foo" instead of "refs/heads/foo", of course.

Now, when it comes to my own local branches, I agree with you: If I make a new local branch "refs/heads/foo" that tracks "refs/remotes/bob/foo", I will probably not want git to copy the branch description automatically.

However, I do agree that putting branch description inside the working tree is not the right solution. So far, the best proposal I've seen, is Hommey's suggestion of storing the description after the sha1 in the ref file itself. Of course, git would have to be taught (a) to handle ref files with descriptions, and (b) to propagate descriptions along with refs.

...Johan

On Wed, 16 April 2008, Johan Herland wrote:

[cut that being able to propagate description of branches is a good idea]

(c) find a place for branch descriptions in packed refs.

Let me sum up here proposals where to put branch description:
1. Put them in branch.<name>.description in repository config. Not easily
   (automatically) propagated for dumb transports.
2. Put them in-tree, which is a bad idea because branches are
   un-versioned (or versioned separately), so branches description
   should also be un-versioned.
3. Put them in GIT_DIR/info/refs_description, in some format.  It makes
   it very easy to add support for propagation for dumb transports.
   Native transport probably would need some extension.  Should not
   interfere with the rest of git code.
4. Store description after sha1 in the ref file itself.  Automatic
   propagation for dumb transport (whether we want it or not).  Native
   transport as above.  Very high probabily of interfering with the rest
   of code, especially shell part of Git.  Need to find a place for
   descriptions in pack-refs.
5. Store them as value of 'refs/heads/<branch>' file in a tree for
   a commit for a special '<description>' separate special branch; at least
   if I understand this proposal correctly.  Something like IIRC the
   'notes' / 'annotations' idea was implemented (on git mailing list;
   it never got into mainline).

I think that the best proposal is (3), not (4) as you say.

On Friday 18 April 2008, Jakub Narebski wrote:

This shouldn't be too hard. Today, we already have one kind of "special" lines in the packed-refs format: "peeled", which uses lines starting with "^". I think we could add another special kind of line called "description" which uses lines starting with "#". Multiline descriptions (if we want to support such) would just have "#" prepended to each line, and the parser would associate all "#"-lines with the most recently parsed ref (like it does for the "^"-line today).

The problem with (3) vs. (4) is that in (3) we must make sure that whenever a branch is moved/renamed (e.g. "git clone", "git branch -m", probably more as well), the corresponding description is moved/renamed as well. This is elegantly solved in (4). But as you say, (4) may have implementation difficulties of its own. I guess the first acceptable implementation will win.

Have fun!

...Johan

Johan Herland <johan@herland.net> writes:

If your "elegently solved" is coming from an assumption that it is enough for "git mv" (for example) to just copy whatever is in .git/refs/heads/foo to .git/refs/heads/bar without understanding what is contained in it, that assumption unfortunately does not hold.

You must support packed refs, so you need to teach the refs infrastructure what per-branch attributes there are other than the commit object name it points at anyway.

And we already do -- when you do "branch -m foo bar", corresponding config entries are also renamed. We also move reflogs.

A possible approach that would work, which contains elements from (4), is to change implementations of loose ref to have this extra info in loose ref files (that is what (4) is), *and* introduce another separate mechanism to store corresponding information for packed refs elsewhere. Propagation needs to deal with both representations, renaming needs to deal with both representations, looking up needs to deal with both representations, everybody needs to deal with both representations.

If you are going to invent "another separate mechanism" to support packed refs anyway, why not use that same mechanism to record information for loose ones as well? That is the approach suggested by (3). In either way we need to teach relevant parts of the code for propagation, renaming, looking up etc about the new mechanism.

On Saturday 19 April 2008, Junio C Hamano wrote:

You're right. Also, after thinking some more about this, it occured to me that most code paths will probably _not_ be interested in branch descriptions at all. It therefore makes sense to keep the descriptions away from the refs themselves, so that they don't impact performance.

So #3 (keeping descriptions in $GIT_DIR/info/refs_description) is probably the best solution.

Have fun! :)

...Johan

On Sat, 19 April 2008, Johan Herland wrote:

[...]

[...]

First, git already has move corresponding reflog and per-branch configuration when renaming a branch, so it is nothing new for (3).

Second, implementation difficulties of (4) might be made stronger by the fact that repository with branches with descriptions should be fetchable and clonable using both native and dumb protocols by older versions of git, and shouldn't cause troubles after fetching. (Assume that git is new enough to understand packed refs). Backward compatibility might kill this solution; but it might not.

BTW. I have added line with description to loose ref, and a few commands I tried didn't return (cause) any errors... so...

Jakub Narebski <jnareb@gmail.com> writes:

Is it really a "mistake" in Mercurial's context?

I thought that their named branches do have defined "starting point", and it is not a mistake at all for them to version "from this point on, this lineage of history is associated with this symbolic name (which is a branch)".

It probably does not make sense in the context of git where a branch is defined to be "illusion" (at least currently).

On Wed, 16 April 2008, Junio C Hamano <gitster@pobox.com> wrote:

I'm sorry, I meant here "tags" not "branch names"... I think...

If we are talking about tags support in Mercurial, I think it is mistake or at least bad design decision. Tags are, and should be, unversioned (or at least versioned separately) but propagated (or rather propagatable). Mercurial offers either in-tree .hgtags, which are always automatically propagated (not merely propagatable); but this mechanism is by default versioned, and Mercurial does complicated dance to get reasonable tags semantic. And there is [theoretical] problem of merging .hgtags file; perhaps solved by specialized merge strategy for this file.

Alternatively Mercurial offers so called local tags, which are not versioned, but not propagated (and AFAIK non propagatable).

So yes, it is a bad design in my opinion.

What happens if there is branching point _after_ such "branch naming tag"? Unless branch names are purely local and non-propagatable, and Mercurial can use local revision numbers or something like this...

I find this CVS legacy to branching (doesn't Subversion use also something like that) to be stupid.

BTW. another tool that has yet another idea of what "branch" is is Monotone, which AFAIK understands branch in reflog sense, via Monotone's signature signatures ;-)

P.S. Cc-ed mercurial mailing list, to give them chance to respond to those "accusations"... if it is not subscribe only...

"Russ Dill" <russ.dill@gmail.com> writes:

Errr... not exactly. It is true that refs such like branches reside outside object database[1], and that names of refs are purely local matter (see old master -> origin mapping, and new refs/heads/* -> refs/remotes/<remote>/* mapping). But you can examine list of branches in remote repository using e.g. git-ls-remote or its equivalent in the git API.

So I think better solution would be to add this info somewhere outside object database, for example in repository config (assuming that not all branches would have description) as it already stores branch related information, _and_ enhance commands to make use of this info, not only git-branch, but also git-for-each-ref, git-show-refs and git-ls-remote (and its equivalents).

Footnotes: ========== [1] And have to be, Mercurial misdesign nothwithstanding