Subject: Re: Stacked GIT 0.1 (a.k.a. quilt for git)

From: Catalin Marinas <[email-masked]>
Date: Sat, 18 Jun 2005 22:35:31 +0100

Daniel,

Thanks for your feedback.

Daniel Barkalow <[email-masked]> wrote:
> It might be worth making the system work for having multiple series in the
> same tree. You could do this by saving the base commit for
> .git/refs/heads/<name> as .git/refs/bases/<name>, and putting patches in
> .git/patches/<name>/. Some people do a lot with
> .git/refs/heads/something; I, at least, symlink .git/HEAD to whichever one
> I'm using, so that might be the right way to tell what the user is
> doing.

Having different series would be a good idea but it might complicate
the tool usage. I will thing about it once I'm sure the basic
operations work fine.

Before commenting further on your or Jon's e-mail, I want to clarify
how I think this tool should be used (this might be misunderstood if
someone never used quilt before). First of all, a StGIT patch is a
collection of git commits. This tool *doesn't* remove or modify git
changesets.

Quilt or StGIT are intended for people maintaining their own (big)
patch on top of the Linux kernel. I will take the example of Con
Kolivas' kernel. His big patch for the -ck kernel is at
http://ck.kolivas.org/patches/2.6/2.6.12-rc6/2.6.12-rc6-ck2/patch-2.6.12-rc6-ck2.diff.bz2.
This big patch is provided mainly for the convenience of the people
wanting to test this kernel. If you want to get deeper into this
patch, you can get it split in several smaller patches
(http://ck.kolivas.org/patches/2.6/2.6.12-rc6/2.6.12-rc6-ck2/patches/).
This set of patches is called a 'series'. You even get a 'series' file
which defines the order in which the patches should be applied.

These patches in a series represent changes to different files grouped
after some criteria. Let's say you have 2 schedulers, you keep them in
2 separate patches. You can modify a scheduler and refresh
(re-generate) its patch with quilt or simply do a 'stg commit' with
StGIT and the change is taken into account for the topmost patch.

Note that the series might remain the same for a long time but the
patches it contains can change. When you want to upgrade the series of
patches to a new kernel version, with quilt or StGIT you pop all the
patches from the stack, upgrade the base (i.e. the mainline kernel)
and push the patches back onto the stack. You can have some of the
patches rejected in quilt or get merge conflicts with StGIT.

While you can simply use quilt patches on top of a git repository,
there are advantages in using StGIT:

- easier integration with a git repository with common commands like
  diff etc.

- there aren't separate commands for adding/removing files to/from the
  git repository and the StGIT patch since a StGIT patch is simply
  represented as two commit ids - the base (bottom) and the top of the
  patch (those familiar with quilt know what it means to modify a file
  without adding it first to the topmost patch)

- every time you commit some changes (with 'stg commit'), this
  changeset is added to the topmost patch on the stack (by replacing
  the top id of the patch with the new commit id). If you want to
  modify a patch, simply push/pop until it becomes the topmost one,
  make the changes and commit. All the commit history is preserved
  (unlike quilt where you update the patch with a 'refresh'
  command). With a future StGIT release you will be able to see the
  log for individual StGIT patches

- pushing a patch to the stack when the base changed is done by
  merging with a diff3 algorithm. I find this slightly superior to a
  simple 'patch -p1 < file.diff' (well, some people do not agree with
  this point)

> I think it would worth exploring defining a git type for patches and
> storing the patches inside git as well. Then a commit could identify the
> patch it applies (when it is from applying a patch), and a rebased patch
> could reference the patch it replaces, and then (with a certain amount of
> handwaving of implementation) the system could notice when the patch
> you're pushing got applied upstream. Or, at least, git could avoid 
> throwing away the history information when it goes through patches. I keep
> thinking that this would be an important feature, but I haven't got the
> familiarity with quilt to know how it should work.

I don't know whether this is still valid after clarifying the intended
use of StGIT. When a patch was merged upstream, the local push
operation should detect that the patch being pushed doesn't change
anything and, at this point, you can safely delete it.

-- 
Catalin