patchgit-merge --squash

Some people tend to do many little commits on a topic branch, recording all the trials and errors, and when the topic is reasonably cooked well, would want to record the net effect of the series as one commit on top of the mainline, removing the cruft from the history. The topic is then abandoned or forked off again from that point at the mainline.

The barebone porcelainish that comes with core git tools does not officially support such operation, but you can fake it by using "git pull --no-merge" when such a topic branch is not a strict superset of the mainline, like this:

	git checkout mainline
	git pull --no-commit . that-topic-branch
	: fix conflicts if any
	rm -f .git/MERGE_HEAD
        git commit -a -m 'consolidated commit log message'
	git branch -f that-topic-branch ;# now fully merged

This however does not work when the topic branch is a fast forward of the mainline, because normal "git pull" will never create a merge commit in such a case, and there is nothing special --no-commit could do to begin with.

This patch introduces a new option, --squash, to support such a workflow officially in both fast-forward case and true merge case. The user-level operation would be the same in both cases:

	git checkout mainline
        git pull --squash . that-topic-branch
        : fix conflicts if any -- naturally, there would be
        : no conflict if fast forward.
	git commit -a -m  'consolidated commit log message'
	git branch -f that-topic-branch ;# now fully merged

When the current branch is already up-to-date with respect to the other branch, there truly is nothing to do, so the new option does not have any effect.

This was brought up in #git IRC channel recently.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 * This is something I am unlikely to use myself, since
   "squashing into one" is too coarse grained for the commits I
   usually make myself.

   If one's habit is to use a sequence of many commits to keep
   too-finer-grained snapshots, and the result of a squash
   commit out of such a sequence of commits is a coherent,
   self-contained unit, then I do not see any reason to
   discourage that workflow.  I however suspect that people who
   make such a sequence of "many too-finer-grained commits"
   would inevitably include changes that do not belong together
   in in one sequence on a topic branch and end up squashing
   them together into one resulting commit.  If that is the
   case, this facility is actively encouraging a bad workflow
   and we should instead teach them to use StGIT or something
   saner.

   But somebody asked on #git channel, so here is the rope.

 Documentation/merge-options.txt |    8 ++++
 git-commit.sh                   |    7 +++-
 git-merge.sh                    |   72 +++++++++++++++++++++++++++++----------
 git-pull.sh                     |    7 +++-
 git-reset.sh                    |    2 +
 5 files changed, 72 insertions(+), 24 deletions(-)

Junio C Hamano <junkio@cox.net> writes:

This part of the commentary needs a bit of clarification, as I realize that I was a bit too negative about this --squash option.

Suppose you have this bright idea for the new filesystem feature that involves some VFS layer changes. Let's call that "frob" feature, and create a topic branch to develop it in.

	git checkout -b frob linus

Now, when you are done, you would want the result to be a nice, neat, logical steps. Perhaps that would introduce features in a sequence like this:

	[PATCH 1/n] vfs: support f_op.frob_read
	[PATCH 2/n] vfs: support f_op.frob_write
        [PATCH 3/n] ext3: add f_op.frob_read and frob_write
        [PATCH 4/n] ramfs: add f_op.frob_read and frob_write
        [PATCH 5/n] vfat: add f_op.frob_read and frob_write
	...

But would you be able to develop things in a neat sequence like this? Probably not. In practice (I do not do kernel myself, so I am just speculating), I would imagine you would pick one filesystem (say ext3) as your initial target, and do the codepath for frob_read operation from bottom to top (vfs to ext3), and then do the same exercise for frob_write codepath, to have something working first. After that, you would start migrating another fs to your updated vfs layer, and during that process you would find your earlier changes to the vfs are insufficient and need further tweaks to support that other fs. So your topic branch with many little snapshot commits might end up looking this way (fictional show-branch output):

  ! [linus] linux-2.6.17
   * [frob] vfs: finishing touches to frob_write
  --
   * [frob] vfs: finishing touches to frob_write
   * [frob~1] vfat: final fix to frob_read to make it work
   * [frob~2] vfs: Oops, vfat is special and frob_write needs this hack
   * [frob~3] vfat: fix support frob_write for disk full condition
   * [frob~4] vfat: support f_op.frob_write
   * [frob~5] ext3, ramfs: give frob_read the extra parameter like vfat does.
   * [frob~6] vfat: give frob_read the extra parameter
   * [frob~7] vfs: frob_read needs an extra parameter for vfat.
   * [frob~8] ramfs: add frob_write, that was easy.
   * [frob~9] ramfs: add frob_read, that was easy.
   * [frob~10] ext3: more frob_write, now ext3 works!
   * [frob~11] ext3: starting to add frob_write
   * [frob~12] vfs: support frob_write
   * [frob~13] vfs: enhance frob_read for special case, now ext3 works!
   * [frob~14] ext3: yet more frob_read
   * [frob~15] ext3: more frob_read
   * [frob~16] ext3: starting to add frob_read
   * [frob~17] vfs: support frob_read
  +* [linus] linux-2.6.17

The --squash merge alone would not help sorting out something like this. However, you could do something like this to separate them out and squash:

	git checkout -b temp master
        for c in 17 13 7 1; do git cherry-pick frob~$c; done
        git checkout master
        git pull --sq . temp
        git commit -a -m 'vfs: support f_op.frob_read'
        git checkout temp
        git reset --hard master
        for c in 12 2 0; do git cherry-pick frob~$c; done
        git checkout master
        git pull --sq . temp
        git commit -a -m 'vfs: support f_op.frob_write'
        git checkout temp
        git reset --hard master
        for c in 16 15 14 11 10 5; do git cherry-pick frob~$c; done
        git checkout master
        git pull --sq . temp
        edit to remove changes to ramfs portion
        git commit -a -m 'ext3: add f_op.frob_read and frob_write'
        ...

So in that sense I would imagine --squash is not really useless in such a situation as I made it sound like, but at the same time I suspect people might be better off to use tools like StGIT which are specially designed to support such a workflow if they were to do this.

Hello Junio,

thanks for --squash. So --squash is basically a 'suck multiple deltas from another branch into ., but don't commit it'. I very often use that way of work flow. I do small and many commits, and when I am done I merge them to one a bit bigger one and submit it upstream. I useally use 'one branch per feature'.

        Thomas

Hi,

On Fri, 23 Jun 2006, Thomas Glanzmann wrote:

Isn't this the same as 'git-cherry-pick -n'? I often do a poor man's StGIT by cherry picking my way through a messy branch, often combining patches by '-n'.

Ciao, Dscho

Hello,

yes it is. I didn't know about the cherry-pick -n option. Thanks.

        Thomas

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Operationally, it probably is equivalent to the repeated use of 'cherry-pick -n' for all commits on a topic, but that would risk you having to resolve conflicts unnecessarily when you are shooting for as the result is a single commit, because you would have to do N merges with that workflow. Squashing is about merging the tip of the topic into mainline, so the conflict resolution needs to be done only once.