7 StGIT is a Python application providing similar functionality to Quilt
8 (i.e. pushing/popping patches to/from a stack) on top of GIT. These
9 operations are performed using GIT commands and the patches are stored
10 as GIT commit objects, allowing easy merging of the StGIT patches into
11 other repositories using standard GIT functionality.
13 Note that StGIT is not an SCM interface on top of GIT and it expects a
14 previously initialised GIT repository (unless it is cloned using StGIT
15 directly). For standard SCM operations, either use plain GIT commands
16 or the Cogito tool but it is not recommended to mix them with the
19 For the latest version see http://www.procode.org/stgit/
25 See the help on individual commands for the full set of options.
30 For a full list of commands:
34 For help on individual commands:
36 stg <cmd> (-h | --help)
38 Repository initialisation/updating
39 ----------------------------------
41 To clone a repository (all the GIT repository types are accepted):
43 stg clone <repository> <local-dir>
45 To initialise an existing GIT repository to be used with StGIT (not
46 needed if the cloning was done using StGIT):
50 For people switching between multiple branches in the same repository,
51 the 'init' command needs to be run for all the branches intended to be
54 To pull the latest changes from the remote repository (defaulting to
55 the value in .git/branches/origin):
57 stg pull [<branch> or 'origin']
59 The 'pull' command takes care of updating all the patches in the stack
60 so that they apply cleanly (the user is notified of the possible
66 To create/delete a patch:
71 The 'new' command also sets the topmost patch to the newly created
74 To automatically delete the empty patches:
78 To push/pop a patch to/from the stack:
80 stg push [--all | <name or first unapplied>]
81 stg pop [--all | <name or topmost>]
83 Note that the 'push' command can apply any patch in the unapplied
84 list. This is useful if one wants to reorder the patches. If there are
85 conflicts, they need to be fixed and 'stg resolved' run. The 'push'
86 operation can also be reverted with 'stg push --undo'.
90 stg rename <old-name> <new-name>
92 To import an existing GNU diff patch file (defaulting to the standard
97 To inspect the stack status:
104 To export a patch series (or a range of patches):
106 stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>]
108 The 'export' command supports options to automatically number the
109 patches (-n) or add the '.diff' extension (-d).
111 To e-mail a patch or range of patches:
113 stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
115 Changes to the topmost patch
116 ----------------------------
118 Any modified file already under revision control will automatically be
119 included in the topmost patch.
121 To add/delete files to/from the topmost patch:
126 To inspect the tree status:
130 To get a diff between 2 revisions:
132 stg diff [-r rev1[:[rev2]]]
134 A revision name can be of the form '([patch]/[bottom | top]) | base |
135 <tree-ish>' If the patch name is not specified but '/' is passed, the
136 topmost patch is used. If neither 'bottom' nor 'top' follows the '/',
137 the whole patch diff is displayed (this does not include the local
140 Note than when the first patch is pushed on the stack, the current
141 HEAD is saved in the .git/refs/heads/base file for easy reference to
142 the base of the stack.
144 To save the tree changes to the current patch and the GIT repository:
148 The 'refresh' command also allows the modification of the patch
149 description and the author/maintainer information.
151 To display the files modified by a patch (defaulting to the topmost
156 To merge a GNU diff file (defaulting to the standard input) into the
161 This command supports a '--threeway' option which applies the patch
162 onto the bottom of the topmost one and performs a three-way merge.
171 StGIT tries to read the configuration options from the following
172 files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides
173 the options in the former files. If no file is found, the defaults are
176 An example configuration file with options description can be found in
177 the examples/ directory. Most users would probably only define the
178 'smtpserver' option used by the 'mail' command.
180 The gitmergeonefile.py script does the three-way merging on individual
181 files using the tool specified by the 'merger' option. The user can
182 specify a smarter tool to be used.
187 The 'export' and 'mail' commands use templates for generating the
188 patch files or e-mails. The default templates are installed under
189 <prefix>/share/stgit/templates/ and, combined with the extra options
190 available for the commands, should be enough for most users. The
191 template format uses the standard Python string formatting rules. The
192 variables available are shown in the the help message for the
195 The 'mail' command can also send an initial e-mail for which there is
196 no default template. The <prefix>/share/stgit/examples/firstmail.tmpl
197 file can be used as an example.
199 A default description for new patches can be defined in the
200 .git/patchdescr.tmpl file. This is useful for things like
203 Dealing with conflicts
204 ----------------------
206 Pushing a patch on the stack can fail if the patch cannot be applied
207 cleanly. This usually happens if there are overlapping changes in the
208 tree, the patch depends on other patch which is not applied or if a
209 patch was not merged upstream in the exact form it was sent.
211 The 'push' operation will stop after the first patch with
212 conflicts. The 'status' command shows the conflict files by marking
213 them with a 'C'. If the 'keeporig' options is set to 'yes' (the
214 default), the original files involved in the merge operations are left
215 in the tree as <file>.older, <file>.local and <file>.remote for a
216 better analysis by the user. If 'diff3' is used as the merger (the
217 default), conflict markers can be found in the corresponding files as
220 Once the conflict is fixed, the 'resolved' command has to be run to
221 clear the conflict state. This command also removes the original files
222 involved in the merge for a given file.
224 Merging two patches into one
225 ----------------------------
227 There is no command to do this directly at the moment but one can
228 export the patch to be merged and use the 'stg fold' command on the
229 generated diff file. Assuming that the merged patch was not already
230 applied, the operation will succeed. Pushing the merged patch onto the
231 stack will result in an empty patch (StGIT notifying the user) that
232 can be safely deleted.
235 .git/ Directory Structure
236 =========================
238 HEAD -> refs/heads/<something>
244 master - the master commit id
247 master - the bottom id of the stack (to get a big diff)
255 applied - list of applied patches
256 unapplied - list of not-yet applied patches
257 current - name of the topmost patch
259 bottom - the bottom id of the patch
260 top - the top id of the patch
261 description - the patch description
262 authname - author's name
263 authemail - author's e-mail
264 commname - committer's name
265 commemail - committer's e-mail
272 A Bit of StGIT Patch Theory
273 ===========================
275 We assume that a patch is a diff between two nodes - bottom and top. A
276 node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
283 Nb - bottom (start) node
285 Nf - first node (for log generation)
287 For an ordered stack of patches:
293 Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
295 Ps - the big patch of the whole stack
296 Nsb - bottom stack node (= N0)
297 Nst - top stack node (= Nn)
299 Applying (pushing) a patch on the stack (Nst can differ from Nb) is
300 done by diff3 merging. The new patch becomes:
304 Nt' = diff3(Nst, Nb, Nt)
306 (note that the diff3 parameters order is: branch1, ancestor, branch2)
308 The above operation allows easy patch re-ordering.
310 Removing (popping) a patch from the stack is done by simply setting