Re: Requirements for integrating a new git subcommand

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 26, 2012, 02:57 UTC
Message-ID: <7vmwy5xe9n.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20121122053012.GA17265@thyrsus.com>

"Eric S. Raymond" <esr@thyrsus.com> writes:

Show 5 quoted lines

> While the weave operation can build a commit graph with any structure
> desired, an important restriction of the inverse (unraveling)
> operation is that it operates on *master branches only*. The unravel
> operation discards non-master-branch content, emitting a warning 
> to standard error when it has to do so.

Imagine that I have a simple four-commit diamond:

    I---A
     \   \
      B---M

where Amy and Bob forked the initial commit made by Ian and created one commit each, and their branches were merged into one 'master' branch by a merge commit made by Mac. How many state snapshots will I see when I ask you to unravel this? Three, or four?

If you are going to give me all four states, then I do not understand why this needs to be limited to the master branch only. Even if you start from a single commit at the tip of 'master', once you hit a merge, you will need to follow all of two (or more) paths to dig down to the root(s), so supporting to start digging from more than one commit is not all that different.

If you are going to give me only three states, following the first parent ancestry chain, then the description needs to state it more clearly. I am not saying first-parent-only history is useless, but the user needs to know that merges are flattened in the unraveled result and the resulting history becomes linear, following the first parent ancestry chain of the original history (if that is what the tool does) before deciding if this tool matches what she needs.

As to the procedural stuff, I think others have sufficiently answered already. If I may add something, a new stuff typically start its life in contrib/ before it proves to be useful.