v2Remote subtree split --annotate

Here's a re-roll with the commit message change suggested by Sebastian. Please apply. Thanks!

From: "David A. Greene" <greened@obbligato.org>

Remove --annotate. This obviates the need for an --unannotate command, which is both an obvious addition and difficult to define due to the numerous ways one might want to specify how to edit commit messages. git has other tools more suited to rewriting commit messages and it's easy enough to use them after a subtree split. Such tools include filter-branch, rebase -i and commit --amend.

Signed-off-by: David A. Greene <greened@obbligato.org>
---
 contrib/subtree/git-subtree.sh     |  6 +----
 contrib/subtree/t/t7900-subtree.sh | 50 +++++++++++++++++++-------------------
 2 files changed, 26 insertions(+), 30 deletions(-)

David Greene <greened@obbligato.org> writes:

I do not think that "there are other ways to do this" is a good justification for removing a feature, unless it can be shown that nobody is using it, of course.

I can see that by changing "printf something" with 'echo -n ""', you are making it clear that we are stopping to add that something to the pipeline, but (1) I think the intended effect of running 'echo -n' on an empty string is to do nothing, and (2) 'echo -n' is not portable [*1*], so this leaves a puzzling code that makes future readers scratch their heads.

I wonder why this cannot be simply the removal of the entire line, making the resulting implementation more like this:

                git log -1 --pretty=format:... "$1" |
                (
                        read ... various variables ...
                        export ... various variables ...
        -		(printf "%s" "$annotate"; cat ) |
                        git commit-tree "$2" $3 # reads the rest of stdin
                ) || die "cannot copy"

That is, just feed the remainder of what is coming directly to the command?

[Footnote]

*1* http://pubs.opengroup.org/onlinepubs/9699919799/utilities/echo.html

says """Implementations shall not support any options."""; '-n' comes from BSD and SysV way of supressing the final newline is to end the string with "\c".

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

I thought you might say that.  :)

I honestly don't know how much it's used. Obviously someone uses it because we got a request a couple of years ago for an --unannotate option and the ensuing discussion made it clear that that's not a trivial thing.

The original author is not active anymore so I don't even know why it was added in the first place. I don't know how to get data about usage.

I'm in the process of getting git-subtree into shape so it can move out of contrib into the main area. Is there a policy for interface changes to things in contrib?

There are a few other things I'm working on that will involve slight semantic changes. I was planning to do those similarly to how push changed with git 2.0. Make the current behavior default, emit a warning and switch the default after a few releases. This is all being done to make git-subtree faster, take advanted of new git features since it was opriginally written and generally make it more solid and predictable. I could do the deprecate/remote thing with --annotate if that sounds better to you.

My thinking on this change runs as follows:

- --annotate isn't as powerful/flexible as other git commit message
  rewrite tools.

- Its obvious pair feature --unannotate isn't trivial to do -- people
  didn't even agree on what it *should* do.  It won't be added any
  time soon, if at all, so don't advertise something that naturally
  leads people to request it.

- We really shouldn't lie about the state of this.  --annotate feels
  tacked-on and incomplete.  It would be best to not have it at all if
  we can't do it right.

- Better to make the change now before moving out of contrib.

If you really don't want to get rid of this, I guess that's ok but my preference as maintainer is to reduce the feature set to those things people seem to actually regularly use (according to my very unscientific Google searches) and add features as requested/evaluated. --annotate isn't a huge maintenance burdern but some of those other changes I mentioned do in fact significantly reduce the maintenance burden of git-subtree. I hope I will have some leeway with those, even if they change semantics slightly.

That makes sense.  Thanks.

                   -David

greened@obbligato.org (David A. Greene) writes:

OK.  It is easy enough to add back when people complains, so...

;-)

Thanks.

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

Thanks.

Just to clarify, what is the expectation of things in contrib? Basically the same as other code?

                    -David

greened@obbligato.org (David A. Greene) writes:

That heavily depends on your exit strategy.

The contrib/ area was created back when Git was still young and we felt that it would be beneficial for building the community if contributions to non-core part were also included, encouraging developers whose strength are not necessarily in the core part to participate in various design-level discussions to grow the community faster. Back then, we felt that an obscure standalone project outside Git that would help the Git-life of users have a much better chance of surviving (and eventually be polished) if we had them bundled, even if the code quality and stability were sub-par.

Those young days are long gone. A standalone tool that aims to help users' Git-life would not just survive but flourish with much more certainty, as long as the tool is good. We have enough Git users to rely on words-of-mouth these days to ensure their success.

That is why I am very hesitant to add new things to contrib/ these days. It is very welcome thought that you are working on improving subtree, and eventually moving it out of contrib/. From the point of view of the project, either moving up (to be part of the git core proper) or moving out (to become an independent project) is far more preferreable than the status quo so far that was staying in contrib/ (without seeing much changes and slowly but steadily bitrotting).

If the aspiration is to move up to exit, then the quality and stability expectation is basically the same as stuff in core, and we need to strive to keep it stable and high quality.

On the other hand, if it is exiting by moving out, then Git-core developers wouldn't have much say in how you would run your project.

There are obvious pros-and-cons from various points of view when choosing between moving up and moving out:

 * If the integration between "git subtree" and the rest of the
   system is loose (in other words, if your improved version of "git
   subtree" taken from Git 2.8 is dropped into an even newer version
   of Git 2.13, or an older version like Git 2.4 for that matter, is
   it expected to work, given the promise of interface stability git
   core gives you?), there is not much technical reason why it must
   stay in core.  Of course, your improvements may need to take
   advantage of improvements on the core side and your new "git
   subtree" may start to require at least Git 2.8, or you may even
   send patches to the core side to extend and enhance the services
   you use from the core side, but as long as that happens only
   occasionally and the dependency does not require lock-step
   upgrade, we can still call such an integration "loose" and moving
   out will still be a viable possibility.

 * If there are many existing users who expect their Git to come
   with "git subtree", unbundling may inconvenience them unless we
   work closely with Distros, from which most of these users get
   their Git.

 * If you expect the pace of improvement would be far faster than
   the release schedule of git core (usually a cycle lasts for 8 to
   12 weeks), moving out would give users a shorter turnaround for
   getting new and improved "git subtree".

 * It may even turn out that the users are a lot more tolerant for
   instability (e.g. removal of rarely used features) in "git
   subtree" than they require the git core proper to be stable, in
   which case moving up (rather than moving out) to apply the same
   stability requirement to "git subtree" as the rest of the system
   would be undesirable.

 * Moving up and staying in has a big social implication. It gives
   the version that comes with git core an appearance of being
   authoritative, even when other people fork the project.

   - This discourages incompatible forks (e.g. when one such fork
     finds the need to improve the "metadata" left by merge
     operation and used by split, the resulting repository managed
     by it may no longer usable by other variants of "git subtree",
     and if there is one in-tree "authoritative" one that is
     maintained, such a fork will not get wide adoption without
     taking compatibility issues into account).

   - On the other hand, if the "authoritative" one moves too slowly,
     that may hinder progress.  An exit by "moving out" to become
     one of the projects that help people's Git-life would result in
     two or more honestly competing forks of "git subtree", which
     might give users a better end-result after a few years, even
     though the users who happened to have picked the losing side
     during these few years may end up having to rewrite the
     history.

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

This is the strategy I was planning to pursue. After extensive experience with git-subtree and some local enhancements I have in real-world work, I am convinced it is a great complementary tool to git-submodule. It seems odd to me to have one in core and one not.

The enhancements to git-subtree that I have and/or am planning to implement will probably require some changes to core, mostly bugfixes. Some of the rebase tests I've sent are heading in that direction. They are problems I discovered while trying to enhance subtree.

I don't think this is a concern.

That's a fair point. Besides than removing this --annotate option, I anticipate two other potentially breaking changes:

1. Reorganizing metadata to be more useful - The metadata tags are
   somewhat misleading at the moment and there is additional metadata
   I've thought about adding.

2. Changing the split algorithm to reuse more of git core -
   Specifically, I would like to leverage filter-branch to eliminate a
   bunch of custom code in the split algorithm.  In fact doing so would
   fix a couple of bugs that have come in.  My intent for this change is
   to not alter the resulting history from what split does now (except
   fixing the known bugs) but I can't absolutely guarantee that will be
   the case until I implement it and try it out.

Other than the metadata rework mentioned above, I personally don't anticipate a lot of change to it. Some ideas have come in from elsewhere but I'm not yet convinced they're necessary. My guess is that any future metadata changes will be more for convenience than any core fnctionality. Thus, they could be added in a backward-compatible way.

That's an important point, especially given the time constraints I have. Despite all my efforts, work is still taking the majority of my coding time. That may improve given some other life schedule changes but we will see. I think I can also justify taking some work time to implement things, since the enhancements are all driven by work needs.

Overall, I think moving subtree to core is the best plan, given submodule's status and the fact that both tools address similar tasks but do them in fundamentally different ways, leading to useful trade-offs for users. One of the things I plan to do is add a section to subtree's documentation that discusses submodule, subtree and reasonable scenarios when one may be a better fit than the other.

                            -David