GSoC idea: allow "git rebase --interactive" todo lines to take options

I just submitted the idea below as a pull request [1] to the GSoC ideas page, but I'd like to get some mailing list feedback first that the idea is sensible...

And, is there anybody else willing to volunteer as a mentor for this project? (There should be at least two.)

Michael

[1] https://github.com/git/git.github.io/pull/5

## Line options for `git rebase --interactive`

One of the more powerful features in Git is the command `git rebase --interactive`, which allows recent commits to be reordered, squashed together, or even revised completely. The command creates a todo list and opens it in an editor. The original todo list might look like:

    pick deadbee Implement feature XXX
    pick c0ffeee The oneline of the next commit
    pick 01a01a0 This change is questionable
    pick f1a5c00 Fix to feature XXX
    pick deadbab The oneline of the commit after

The user can edit the list to make changes to the history, for example to

    pick deadbee Implement feature XXX
    squash f1a5c00 Fix to feature XXX
    exec make
    edit c0ffeee The oneline of the next commit
    pick deadbab The oneline of the commit after

This would cause commits `deadbee` and `f1a5c00` to be squashed together into one commit followed by running `make` to test-compile the results, delete commit `01a01a0` altogether, and stop after committing commit `c0ffeee` to allow the user to make changes.

It would be nice to support more flexibility in the todo-list commands by allowing the commands to take options. Maybe

* Convert a commit into a merge commit:

      pick -p c0ffeee -p e1ee712 deadbab The oneline of the commit after

* After squashing two commits, add a "Signed-off-by" line to the
  commit log message:

    pick deadbee Implement feature XXX
    squash --signoff f1a5c00 Fix to feature XXX

  or GPG-sign a commit:

    pick --gpg-sign=<keyid> deadbee Implement feature XXX

* Reset the author of the commit to the current user or a specified
  user:

    pick --reset-author deadbee Implement feature XXX
    pick --author="A U Thor <author@example.com>" deadbab The oneline of
the commit after

The goal of this project would be (1) to add the infrastructure for handling options on todo-list lines, and (2) implement some concrete options. A big part of the difficulty of this project is that `git rebase --interactive` is implemented via a sparsely-commented shell script. Adding comments and cleaning up the script as you go would be very welcome.

 - Language: sh
 - Difficulty: medium
 - Possible mentors: Michael Haggerty

On Wed, Feb 26, 2014 at 09:04:30AM +0100, Michael Haggerty wrote:

This seems like a reasonable feature to me. All of your examples are possible with an "e"dit and another git command, but the convenience may be worth it (though personally, most of the examples you gave are particularly interesting to me[1]).

I'd worry a little that it is not a summer's worth of work, but I suspect there are other parts of rebase--interactive that could use attention once the student is familiar with the code.

Your first example would need some commit-tree magic, I think. But could you implement these two with:

   pick deadbee Implement feature XXX
   exec git commit --amend --signoff --reset-author

? You could even alias the "amend" command to "exec git commit --amend", like:

  amend --signoff --reset-author

Maybe that is unnecessarily unfriendly to the user, though.

-Peff

[1] The one feature I would like in this vein is that editing the title
    in the instruction-sheet would modify the commit message of the
    relevant commit. For some reason I try to do this every few weeks,
    but of course the changes are just thrown away.

On 02/26/2014 11:52 AM, Jeff King wrote:

The whole point is to make these things easy. But I have to admit that "amend" would be another nice todo-list command. Once the infrastructure is there to handle options, it would be no big deal to add an "amend" command with a "--signoff" option and offer the same "--signoff" option on other, existing commands.

Given that commit messages can be more than one line long, a feature like this would be confusing, I think, and perhaps subtly encourage people to limit their commit messages to a single line, which would be a bad thing. Plus, until now such edits were thrown away, so there are backwards compatibility problems if we suddenly start preserving such edits.

But using the other ideas discussed here one could do

    pick -m "New log message" <sha1>

or

    amend -m "Revised log message"

It also might be reasonable, if the user edits the title in a way that does not simply delete characters at the end, to do an implicit "reword" with the edited title stuck in at the first line (and maybe the original title following it, commented out with "#").

Another, more wonkish idea I though of would be

    pick --tree=<treeish> <sha1>

to force the tree of the commit to be set to that of the specified <treeish> while keeping the commit metadata from <sha1>. What would this be useful for? When swapping two commits, it is often the case that conflicts have to be resolved twice. But the tree should be the same after both commits are applied, regardless of the order in which they are applied. So one could change

    pick aaaaaaa
    pick bbbbbbb

to

    pick bbbbbbb
    pick --tree=bbbbbbb aaaaaaa

On the other hand, maybe "git rebase --interactive" should have the intelligence to do this automatically whenever the set of commits pre/post rewriting is identical, possibly if a "--reorder-only" option is used.

Michael

On Wed, Feb 26, 2014 at 12:14:11PM +0100, Michael Haggerty wrote:

Right, I was assuming it would just modify the subject-line, and leave the rest intact (I often want to use it to just replace one word or fix a typo, since I am starting right at it in the insn sheet).

Good point. For true interactive use it probably wouldn't be that big a deal, but people do weird things with GIT_EDITOR and auto-munging the list of commits. A heuristic like "is there any message there at all" might work, as you mentioned, but heuristics make me nervous.

Yeah, that would work, though you have to retype the whole thing, which is potentially annoying (clever use of your editor can pull it over from the other side, but it's not super-friendly).

Something like:

  pick --subject <sha1> <modified message...>

would be simpler.

That would replace the whole message, which I definitely don't want (and would encourage bad habits).

I think there's a large foot-shooting capacity there. Any commit you've reordered from after the "--tree" to before it will mysteriously get undone in the "--tree" commit. E.g.:

  pick aaaaaaa
  pick bbbbbbb
  pick ccccccc

being done as:

  pick ccccccc
  pick bbbbbbb
  pick --tree=bbbbbbb aaaaaaa

-Peff

On Wed, Feb 26, 2014 at 6:52 PM, Jeff King <peff@peff.net> wrote:

It might be worthwhile to check for prior projects that were a "bag" of small projects that were accepted into GSoC. I don't have the time to do this right now, I'll get to it at a later time.

Jeff King <peff@peff.net> writes:

I actually had a completely opposite reaction to the above one. It took considerable mental effort to decipher what that "pick -p ..." line was trying to do, and I am not absolutely sure if I understand what it is trying to do enough to rewrite it to an equivalent "inconvenient" sequence of "edit and another git command".

Every time I thought about this one, I get stopped after realizing that the title line is only a small part of the log message.

On 02/26/2014 11:52 AM, Jeff King wrote:

Don't forget that any of the parent commits might have been rewritten due to the earlier lines of the rebase script. Rebase has to map the specified SHA-1s to their new versions. So I don't think that this one would be very practical to implement by hand.

Actually I think it is awkward to have to specify all of the parent commits. I did it this way to make it look like commit-tree's -p option. But any usage of this feature that *doesn't* include the immediately preceding commit as a parent would probably be broken anyway (for example, the preceding commit would become unreachable).

So maybe a better UI would be

    pick --merge=e1ee712 deadbab The oneline of the commit after

(even though this precludes the short form "-m" because it is already taken by --message).

On the other hand, allowing arbitrary parents with "-p" might be a way to make "rebase --interactive" work half-sanely with parts of history that *already* include merge commits. The todo list that rebase prepares for the user would already include these "-p" lines.

What I like about allowing options in todo lists is that is that it opens up a lot of possibilities for "git rebase --interactive" that, I think, have previously been hampered by the restriction that commands have to consist of a single word, and (until now) have to be abbreviable to a single distinct letter.

Michael

On Wed, Feb 26, 2014 at 5:52 AM, Jeff King <peff@peff.net> wrote:

This strikes me as over-complicating the rebase --interactive interface. Particularly all of the ideas expressed later on about merge commits and resetting authors, etc. It seems like you're trying to define a whole new command set (i.e., API) for Git, but within the context of rebase --interactive. I think it would be hard to document this, and hard to learn it, and harder still to remember it (even though it would obviously try to mirror the existing Git command API). I honestly didn't know (or forgot) about the e"x"ec command, but that to me says that I can automate whatever I want without needing to make any changes to the rebase --interactive interface. The advantage to this is that we don't need to reinvent the square wheel that is the Git command API. We can just exec git ... with the exact same command set and options that we're already familiar with. No doubts about syntax or disparities, etc.

I don't think it's my place to resist these changes; particularly because I don't think they'd necessarily affect me, except for maybe the proposed automatic merge support, but if that SOMEHOW actually works reliably and sensibly (i.e., to allow you to rebase over merges without losing the merges) I'm not sure I'd complain. That said, I do think that this is probably a bad direction and shouldn't be rushed into too fast. It seems like it would be a complicated thing to do, more complicated to do well, and I'm not sure that it would really improve things any. I'm not sure that users would prefer to use this over "e"diting and/or e"x"ecing instead. Plus where do you draw the line as far as which features to reproduce? How do you prevent scope creep?

When I do this I am usually half asleep and it's a good reminder to pay attention to what I'm doing. I'd probably rather Git *error* when I change the subject line and tell me why it doesn't make sense and recommend "r"eword instead.

Regards,

On Thu, Feb 27, 2014 at 01:10:30PM -0500, Brandon McCaig wrote:

Sorry, I missed an important word in my final sentence. It should have been "the examples you gave are NOT particularly interesting to me".

I agree some of the examples are getting esoteric. Things like --signoff and --reset-author are a fairly straightforward convenience feature: they save you from writing "exec git commit --amend --signoff".

For others that cannot currently be done with a simple option to "git commit", I think a reasonable first step would be to implement them there. For example, you cannot currently "git commit --tree". Maybe that is too insane and low-level an option for "git commit". But if it is, then it is almost certainly too insane and low-level for a rebase instruction.

For others from Michael's list, I expect they may not make _sense_ outside of a rebase. That is, they are operations whose input is not a single commit, but a sequence of commits (e.g., if you had some high-level command that allowed swapping two commits without having to redo the conflicts from the second commit). Those ones might make sense to exist as part of rebase and nowhere else (but then they are not necessarily just options, but rather new instructions).

I'm not sure whether it is a good idea or not. But I think it is looking decreasingly like a good GSoC project.

-Peff

On 02/28/2014 01:52 PM, Jeff King wrote:

I guess I misread the sentiment of the mailing list, because I merged this idea into the list about two hours ago.

I'm not claiming that all of the sub-ideas are good, but I do think that some of them are, and that the general idea of allowing options on todo-list commands would make it possible for them to be more expressive while *avoiding* making them a lot harder to learn. I would rather give the user a few options that can be used consistently on multiple commands than have to invent a new command for each new feature. And I think that the line-oriented nature of the todo list makes

    pick --signoff 1234abc Blah blah

easier to understand (and easier to type) than

    pick 1234abc Blah blah
    amend --signoff

let alone

    pick 1234abc Blah blah
    exec git commit --amend --signoff

I also like the idea of a non-broken "git rebase --interactive --preserve-merges" via a todo option "-p" or something similar.

But if you think that even the proposal's simpler sub-ideas are controversial, then let me know and I will delete the idea from the list again. I don't want a GSoC student to have to fight battles of my own creation :-)

Michael

On Fri, Feb 28, 2014 at 03:03:52PM +0100, Michael Haggerty wrote:

Yeesh, sorry to be so slow on the reply to this. It floated to the bottom of my "to respond" list.

I'd say keep it at this point. I think there _are_ some good ideas here, and part of a project is figuring out what is good. And part of the role of the mentor is applying some taste. There are probably students who would be a good fit, and students who would not. That is true for just about every project, of course, but I think this one is just a little trickier than some.

-Peff

Jeff King <peff@peff.net> writes:

Amen to that. I hope we have enough mentor-candidates with good taste, though ;-)

Perhaps.