RFC patch, 4 partsrebase -i: Add --refs option to rewrite heads within branch

This RFC series adds a "ref" command to rebase -i, and an option --refs to generate "ref" commands in the original TODO file. This makes it easy to rebase a branch together with intermediate markers, or a series of branches.

For example, in this situation:

      part1 part2 topic
        |     |     |
        v     v     v
  A--*--*--*--*--*--*
   \
    B <--master

we may want to rebase 'topic' onto the new master, rewriting the intermediate branches 'part1', 'part2' to the corresponding new commits. This can be done with a sequence of "git rebase --onto" commands, but it's tricky to get right.

With this series, the command
  $ git rebase -i --refs master topic
suffices to produce this result:

        part1 part2 topic
  A       |     |     |
   \      v     v     v
    B--*--*--*--*--*--*
    ^
    |
    master

These patches work for me.  Before I recommend the last two patches
for merge, they'll need the following additional work:
 - interoperate with rebase --abort
 - add documentation
 - probably add tests

The series begins with two patches that are independently useful, and
that I believe are ready for merge:
  pretty: Add %D for script-friendly decoration
  log --decorate=full: drop the "tag: " prefix
They make the functionality of 'git log --decorate' available in an
output format optimized for machine parsing.  I expect other people
will find this useful for other scripts.

Greg

When in a script or porcelain one wants to identify what refs point to which commits in a series, the functionality of 'git log --decorate' is extremely useful. This is available with the %d format code in a form optimized for humans, but for scripts a more raw format is better. Make such a format available through a new format code %D.

Signed-off-by: Greg Price <price@ksplice.com>
---
 Documentation/pretty-formats.txt |    1 +
 pretty.c                         |   33 +++++++++++++++++++++++++--------
 2 files changed, 26 insertions(+), 8 deletions(-)

The "tag: " prefix complicates machine parsing of decorations, so we drop it from the output formats intended to be parsed by machine, namely --decorate=full and the %D format code.

The prefix is helpful for a human reader to see that the ref is an (annotated) tag, especially since we omit the "refs/tags/" prefix in the default output of "git log --decorate". In a script, however, it is easy to use "git cat-file -t" to distinguish annotated tags from commits when the distinction is relevant.

Signed-off-by: Greg Price <price@ksplice.com>
---
 log-tree.c |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

This is useful for, e.g., rewriting a branch that has ancestor branches along the way.

Signed-off-by: Greg Price <price@ksplice.com>
---
 git-rebase--interactive.sh |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

The new option --refs causes the TODO file to contain a "ref" command for each head pointing to a selected commit, other than the one we are already rebasing. The effect of this is that when a branch contains intermediate branches, like so:

      part1 part2 topic
        |     |     |
        v     v     v
  A--*--*--*--*--*--*
   \
    B <--master

a single command like "git rebase -i --refs master topic" suffices to rewrite all the heads that are part of the topic, like so:

        part1 part2 topic
  A       |     |     |
   \      v     v     v
    B--*--*--*--*--*--*
    ^
    |
    master

Signed-off-by: Greg Price <price@ksplice.com>
---
 git-rebase--interactive.sh |   22 ++++++++++++++++++++--
 1 files changed, 20 insertions(+), 2 deletions(-)

Greg Price <price@ksplice.com> writes:

Two comments and a half.

 - As decoration is a fairly expensive operation (which is the reason why
   loading_ref_decorations() is called lazily by format_decoration() in
   the first place, especially in repositories with tons of refs), you
   shouldn't give --format=%D to rev-list when the new feature is not
   asked for.

 - This seems to rewrite only branch heads; don't you want to allow users
   to rewrite lightweight tags and possibly annotated ones as well, by
   perhaps giving "--rewrite-refs=refs/heads/" or "--rewrite-refs=refs/"
   to limit what parts of the ref namespace to consider rewriting?

 - Otherwise the option should not be called "refs" but be named using the
   word "branch" to clarify that it affects _only_ branches.

Obviously the series also needs tests.

I also have to wonder if this feature should also handle a case like this:

                  side
                  |
                  V
                  *
                 /
        part1   *    topic
          |    /      |
          v   /       v
    A--*--*--*--*--*--*
     \
      B <--master

===>

                     side
                     |
                     V
                     *
                    /
           part1   *    topic
     A       |    /      |
      \      v   /       v
       B--*--*--*--*--*--*
       ^
       |
       master

especially if it were to be specific to branch management.

On the other hand, if the "partN" markers in your example workflow are primarily meant to be used to mark places on a branch (as opposed to arbitrary branch tips that independent development starting from them can further continue), it would make a lot more sense to use lightweight or annotated tags for them, and instead of "--refs" that rewrites only other branch tips, it might make a lot more sense to have "--rewrite-tags" that rewrites tags that point at the commits that are rewritten, without touching any branch tip.

On Tue, Dec 22, 2009 at 6:37 PM, Junio C Hamano <gitster@pobox.com> wrote:

OK, will do.

Sure. I specifically left out tags because I generally think of a tag as something immutable that it would not make sense to rewrite. But people use Git in different ways and it makes sense to give the option of rewriting tags as well as heads.

I do worry that passing --rewrite-refs=refs/ will set up remote refs for rewriting, which is likely to be confusing if the user does not notice them and remove them from the TODO. Perhaps it makes sense to accept forms like "--rewrite-refs=refs/heads/,refs/tags/" or "--rewrite-refs=refs/heads/ --rewrite-refs=refs/tags/". Is there a Git convention for accepting a sequence of arguments like this to an option -- one of these, or something else?

I think of them as a topic branch developing one feature, then another branch developing a related follow-on feature, etc. I would also feel odd rewriting tags as a routine operation, or calling a ref a tag when I expect to rewrite it. So I do think they're best recorded as branch tips rather than tags.

Yes.

Huh, that's an interesting idea.  I hadn't thought of that.  This
feature could be nice.  But I am not sure what it would look like.
How might the user indicate that they want both "side" and "topic" to
be rebased?  I suppose we could extend the familiar command line
   git rebase <upstream> [<branch>]
to the form
   git rebase <upstream> [...<branches>...]
so that your example would be
   $ git rebase -i --rewrite-heads master topic side
If we choose this approach, it might even be independent of
--rewrite-refs, though the implementation would presumably rely on the
"ref" command.  Was this interface what you were thinking, or do you
have another idea?

Greg

Greg Price venit, vidit, dixit 23.12.2009 08:03:

If I may jump in: I imagine this to be the more common use case, i.e.: You have a part of the DAG which you want to rebase, with all kinds of refs (branches, tags) pointing to commits in that part of the DAG. If you rebase that part of the DAG you typically want some refs rewritten (such as the head of the branch you're rebasing) but maybe not others (say a release tag or branch). remote refs should never be rebased. So, one would need an easy way to specify one ref, all or anything in between...

Michael

On Wed, Dec 23, 2009 at 3:53 AM, Michael J Gruber <git@drmicha.warpmail.net> wrote:

I see the interactive aspect as the backstop that gives the user total flexibility, whatever command-line interface we choose. So, for example, a user might find it easiest to pass --rewrite-heads so that all heads on the given part of the DAG are inserted as "ref" commands in the appropriate places, and then go through and remove from the TODO file any exceptions.

But I agree it is worth making convenient shortcuts by which the user can specify their intention precisely on the command line itself. And in any case, if we are to satisfy this latter use case we need a way of specifying a part of the DAG to rebase that is not only ancestors of a single commit. What do you think of the "--rewrite-refs=refs/heads/,refs/tags/" and "git rebase -i master topic side" proposals in my reply to Junio?

Greg

Michael J Gruber <git@drmicha.warpmail.net> writes:

And warn (or perhaps reject without --force) if the sub-DAG you would rebase contains an already tagged commit, especially if you are treating tags as immutable, even the ones you haven't published.

I actually don't think "rebasing side branches while rebasing this branch" was such a good idea---we have filter-branch for that already ;-).

Hi,

On Wed, 23 Dec 2009, Greg Price wrote:

I do agree: if you plan to rewrite a ref, you _should_ make it a branch anyway.

A tag is not meant to be updated easily, in fact, we explicitely lack tools to do so (and it is quite hard to get updated tags from a repository where the tags changed anyway). So rewriting tags is something that causes only trouble.

Why should rebase -i cause that trouble all of a sudden?

Ciao, Dscho