4 StGIT is a Python application providing similar functionality to Quilt
5 (i.e. pushing/poping patches to a stack) on top of GIT. These
6 operations are performed using the GIT merge algorithms.
8 Note that StGIT is not an SCM interface for GIT. Use the GIT commands
9 or some other tools like Cogito for this.
11 For the latest version see http://www.procode.org/stgit/
17 For a full list of commands:
21 For help on individual commands:
23 stg <cmd> (-h | --help)
25 To initialise a tree (the tree must have been previously initialised
35 To inspect the tree status:
39 To get a diff between 2 revisions:
41 stg diff [-r rev1[:[rev2]]]
43 A revision name can be of the form '([patch]/[bottom | top]) | <tree-ish>'
44 If the patch name is not specified but '/' is passed, the topmost
45 patch is considered. If neither 'bottom' or 'top' follows the '/', the
46 whole patch diff is displayed (this does not include the local
49 Note than when the first patch is pushed to the stack, the current
50 HEAD is saved in the .git/refs/heads/base file for easy reference.
52 To create/delete a patch:
55 stg delete [<name or topmost>]
57 The 'new' command also sets the topmost patch to the newly created
60 To push/pop a patch to/from the stack:
62 stg push [<name or first unapplied>]
63 stg pop [<name or topmost>]
65 Note that the 'push' command can apply any patch in the unapplied
66 list. This is useful if you want to reorder the patches.
68 To add the patch changes to the tree:
72 To inspect the patches applied:
79 To export a patch series:
81 stg export [<dir-name or 'patches'>]
83 The 'export' command supports options to automatically number the
84 patches (-n) or add the '.diff' extension (-d).
86 StGIT does not yet provide support for cloning or pulling changes from
87 a different repository. Until this becomes available, run the
91 your-git-script-for-pulling-and-merging
94 You can also look in the TODO file for what's planned to be
95 implemented in the future.
107 master - the master commit id
110 master - the bottom id of the stack (to get a big diff)
118 applied - list of applied patches
119 unapplied - list of not-yet applied patches
120 current - name of the topmost patch
122 first - the initial id of the patch (used for log)
123 bottom - the bottom id of the patch
124 top - the top id of the patch
129 HEAD -> refs/heads/<something>
132 A Bit of StGIT Patch Theory
133 ---------------------------
135 We assume that a patch is a diff between two nodes - bottom and top. A
136 node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
143 Nb - bottom (start) node
145 Nf - first node (for log generation)
147 For an ordered stack of patches:
153 Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
155 Ps - the big patch of the whole stack
156 Nsb - bottom stack node (= N0)
157 Nst - top stack node (= Nn)
159 Applying (pushing) a patch on the stack (Nst can differ from Nb) is
160 done by diff3 merging. The new patch becomes:
164 Nt' = diff3(Nst, Nb, Nt)
166 (note that the diff3 parameters order is: branch1, ancestor, branch2)
168 The above operation allows easy patch re-ordering.
170 Removing (popping) a patch from the stack is done by simply setting