Re: Requirements for integrating a new git subcommand

[Junio C Hamano <gitster@pobox.com>]

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

> 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.