4 StGIT is a Python application providing similar functionality to Quilt
5 (i.e. pushing/popping patches to/from a stack) on top of GIT. These
6 operations are performed using GIT commands and the patches are stored
7 as GIT commit objects, allowing easy merging of the StGIT patches into
8 other repositories using standard GIT functionality.
10 Note that StGIT is not an SCM interface on top of GIT and it expects a
11 previously initialised GIT repository (unless it is cloned using StGIT
12 directly). For standard SCM operations, either use plain GIT commands
13 or the Cogito tool but it is not recommended to mix them with the
16 For the latest version see http://www.procode.org/stgit/
22 See the help on individual commands for the full set of options.
27 For a full list of commands:
31 For help on individual commands:
33 stg <cmd> (-h | --help)
35 Repository initialisation/updating
36 ----------------------------------
38 To clone a repository (all the GIT repository types are accepted):
40 stg clone <repository> <local-dir>
42 To initialise an existing GIT repository to be used with StGIT (not
43 needed if the cloning was done using StGIT):
47 For people switching between multiple branches in the same
48 repository, the 'init' command needs to be run for all the branches
49 intended to be used with StGIT.
51 To pull the latest changes from the remote repository (defaulting to
52 the value in .git/branches/origin):
54 stg pull [<branch> or 'origin']
56 The 'pull' command takes care of updating all the patches in the
57 stack so that they apply cleanly (the user is notified of the
63 To create/delete a patch:
68 The 'new' command also sets the topmost patch to the newly created
71 To automatically delete the empty patches:
75 To push/pop a patch to/from the stack:
77 stg push [--all | <name or first unapplied>]
78 stg pop [--all | <name or topmost>]
80 Note that the 'push' command can apply any patch in the unapplied
81 list. This is useful if one wants to reorder the patches. If there
82 are conflicts, they need to be fixed and 'stg resolved' run. The
83 'push' operation can also be reverted with 'stg push --undo'.
87 stg rename <old-name> <new-name>
89 To import an existing GNU diff patch file (defaulting to the
94 To inspect the stack status:
101 To export a patch series (or a range of patches):
103 stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>]
105 The 'export' command supports options to automatically number the
106 patches (-n) or add the '.diff' extension (-d).
108 To e-mail a patch or range of patches:
110 stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
112 Changes to the topmost patch
113 ----------------------------
115 Any modified file already under revision control will automatically
116 be included in the topmost patch.
118 To add/delete files to/from the topmost patch:
123 To inspect the tree status:
127 To get a diff between 2 revisions:
129 stg diff [-r rev1[:[rev2]]]
131 A revision name can be of the form '([patch]/[bottom | top]) | base
132 | <tree-ish>' If the patch name is not specified but '/' is passed,
133 the topmost patch is used. If neither 'bottom' nor 'top' follows the
134 '/', the whole patch diff is displayed (this does not include the
137 Note than when the first patch is pushed on the stack, the current
138 HEAD is saved in the .git/refs/heads/base file for easy reference to
139 the base of the stack.
141 To save the tree changes to the current patch and the GIT
146 The 'refresh' command also allows the modification of the patch
147 description and the author/maintainer information.
149 To display the files modified by a patch (defaulting to the topmost
154 To merge a GNU diff file (defaulting to the standard input) into the
159 This command supports a '--threeway' option which applies the patch
160 onto the bottom of the topmost one and performs a three-way merge.
169 StGIT tries to read the configuration options from the following
170 files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides
171 the options in the former files. If no file is found, the defaults are
174 An example configuration file with options description can be found in
175 the examples/ directory. Most users would probably only define the
176 'smtpserver' option used by the 'mail' command.
178 The gitmergeonefile.py script does the three-way merging on individual
179 files using the tool specified by the 'merger' option. The user can
180 specify a smarter tool to be used.
185 The 'export' and 'mail' commands use templates for generating the
186 patch files or e-mails. The default templates are installed under
187 <prefix>/share/stgit/templates/ and, combined with the extra options
188 available for the commands, should be enough for most users. The
189 template format uses the standard Python string formatting rules. The
190 variables available are shown in the the help message for the
193 The 'mail' command can also send an initial e-mail for which there is
194 no default template. The <prefix>/share/stgit/examples/firstmail.tmpl
195 file can be used as an example.
197 A default description for new patches can be defined in the
198 .git/patchdescr.tmpl file. This is useful for things like
201 Dealing with conflicts
202 ----------------------
204 Pushing a patch on the stack can fail if the patch cannot be applied
205 cleanly. This usually happens if there are overlapping changes in the
206 tree, the patch depends on other patch which is not applied or if a
207 patch was not merged upstream in the exact form it was sent.
209 The 'push' operation will stop after the first patch with
210 conflicts. The 'status' command shows the conflict files by marking
211 them with a 'C'. If the 'keeporig' options is set to 'yes' (the
212 default), the original files involved in the merge operations are left
213 in the tree as <file>.older, <file>.local and <file>.remote for a
214 better analysis by the user. If 'diff3' is used as the merger (the
215 default), conflict markers can be found in the corresponding files as
218 Once the conflict is fixed, the 'resolved' command has to be run to
219 clear the conflict state. This command also removes the original files
220 involved in the merge for a given file.
222 Merging two patches into one
223 ----------------------------
225 There is no command to do this directly at the moment but one can
226 export the patch to be merged and use the 'stg fold' command on the
227 generated diff file. Assuming that the merged patch was not already
228 applied, the operation will succeed. Pushing the merged patch onto the
229 stack will result in an empty patch (StGIT notifying the user) that
230 can be safely deleted.
233 .git/ Directory Structure
234 =========================
236 HEAD -> refs/heads/<something>
242 master - the master commit id
245 master - the bottom id of the stack (to get a big diff)
253 applied - list of applied patches
254 unapplied - list of not-yet applied patches
255 current - name of the topmost patch
257 bottom - the bottom id of the patch
258 top - the top id of the patch
259 description - the patch description
260 authname - author's name
261 authemail - author's e-mail
262 commname - committer's name
263 commemail - committer's e-mail
270 A Bit of StGIT Patch Theory
271 ===========================
273 We assume that a patch is a diff between two nodes - bottom and top. A
274 node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
281 Nb - bottom (start) node
283 Nf - first node (for log generation)
285 For an ordered stack of patches:
291 Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
293 Ps - the big patch of the whole stack
294 Nsb - bottom stack node (= N0)
295 Nst - top stack node (= Nn)
297 Applying (pushing) a patch on the stack (Nst can differ from Nb) is
298 done by diff3 merging. The new patch becomes:
302 Nt' = diff3(Nst, Nb, Nt)
304 (note that the diff3 parameters order is: branch1, ancestor, branch2)
306 The above operation allows easy patch re-ordering.
308 Removing (popping) a patch from the stack is done by simply setting