Re: Converting commits to patch files? HEAD vs HEAD^

[Catalin Marinas <catalin.marinas@gmail.com>]

Junio C Hamano <junkio@cox.net> wrote:
>>>>>> "MS" == Marc Singer <elf@buici.com> writes:
> MS> If I've made several commits, I'd like to be able to gather several
> MS> together and produce a patch file.  Better still, I'd like to be able
> MS> to pick a set of discontiguous commits an bundle them into a single
> MS> patch.  Ought I be using tags?
>
> Although I have not looked at it myself, you may want to take a
> look at StGIT.

I still haven't found time to write a tutorial for StGIT (it has a
README but I haven't updated it for some time) but I will try to give
a short description. People familiar with Quilt should not have any
problem with using this tool (it is safer than quilt).

StGIT is well suited for working on trees you do not control (you send
patches and wait for them to be merged and eventually get them from
the remote repository when pulling the latest changes). The advantage
over quilt is that it uses three-way merging and also informs you when
your local patch is empty (i.e., after the patch was fully merged
upstream, quilt just failing to push the patch in this case because of
conflicts).

In general, you clone a repository (Linus' for example) and run
'stg init' to initialise the StGIT specific files.

There is no 'commit' command in StGIT. To make changes, create a patch
with 'stg new <name>' and add some description (can be modified at any
time with the 'refresh --edit' command). You make changes to the files
(or add/rm files) and save them (can be done for an indefinite number
of times) into the current patch with 'stg refresh'. This last command
creates a GIT commit object for the changes between the working tree
and the bottom of the patch (which can be the upstream HEAD if this is
the first patch).

You can create several patches with 'stg new'. A 'git log' command
would show the patches as individual commits. The advantage over a
normal SCM is that you can modify the patch and replace the commit
object with a new one.

To work on a given patch, make it current via the 'stg push/pop'
commands. Note that 'stg push' also allows patch re-ordering.

To pull the latest changes from the upstream respository, do a 'stg
pop -a' (at this point the tree is the same as the one when you last
pulled the remote changes), 'git pull', 'stg push -a'. You can get
conflicts for the latter command if there are overlapping changes or
the patch was modified by the gatekeeper before being merged. Fix the
conflicts, run 'stg resolved/stg refresh' and re-run 'stg push -a' for
the rest of the patches. The 'push' and the 'series' commands notify
you if the patch is empty so that it can safely be removed ('stg
delete <name>').

To send patches upstream (the 'mail' command is not available yet),
you can export the patches with 'stg export' and e-mail manually. You
can create your own template for the exported patch (to include
description, diffstats etc.). An temlate example is given in the
archive, just copy it to the .git/ directory.

Another way to send patches is to ask the gatekeeper to pull from your
tree. Run 'stg push' for all the patches you want to be merged and the
HEAD of your tree would contain the commit objects.

-- 
Catalin