Commit | Line | Data |
---|---|---|
c2428e5a CM |
1 | StGIT Tutorial |
2 | ============== | |
d1c8fcd7 CM |
3 | |
4 | Introduction | |
c2428e5a | 5 | ------------ |
d1c8fcd7 | 6 | |
c2428e5a CM |
7 | StGIT is a Python application that provides functionality similar to |
8 | quilt (i.e. pushing/popping patches to/from a stack) using GIT instead | |
9 | of 'diff' and 'patch'. StGIT stores its patches in a GIT repository as | |
10 | normal GIT commit objects. | |
11 | StGIT is not an SCM interface on top of GIT. For standard SCM | |
12 | operations, either use GIT's porcelain commands or the Cogito tool. | |
13 | StGIT is available for download at http://www.procode.org/stgit/ . | |
14 | This tutorial assumes you are already familiar with GIT. For more | |
15 | information on GIT, see the GIT_tutorial or git(7) . | |
d1c8fcd7 | 16 | |
d1c8fcd7 | 17 | |
c2428e5a CM |
18 | Basic Operation |
19 | =============== | |
d1c8fcd7 CM |
20 | |
21 | Help | |
22 | ---- | |
23 | ||
c2428e5a | 24 | For a full list of StGIT commands: |
d1c8fcd7 CM |
25 | |
26 | stg help | |
27 | ||
c2428e5a | 28 | For help on individual subcommands: |
d1c8fcd7 CM |
29 | |
30 | stg <cmd> (-h | --help) | |
31 | ||
d1c8fcd7 | 32 | |
c2428e5a CM |
33 | Repository initialisation |
34 | ------------------------- | |
d1c8fcd7 | 35 | |
c2428e5a CM |
36 | In stand-alone mode, StGIT is used in conjunction with a GIT repository |
37 | that is already initialised (using 'git-init-db'). StGIT cannot be used | |
38 | outside of a GIT repository. | |
39 | Any branch in a GIT repository may be managed by StGIT. Each branch | |
40 | managed by StGIT contains an independent series of StGIT patches. | |
41 | To initialise an existing GIT branch to be managed by StGIT, cd into the | |
42 | top of your GIT repository, check out the branch you'd like to manage | |
43 | with StGIT, and type: | |
d1c8fcd7 CM |
44 | |
45 | stg init | |
46 | ||
c2428e5a CM |
47 | Run the 'stg init' command for any pre-existing GIT branches intended to |
48 | be used with StGIT. | |
49 | You can switch between GIT branches with: | |
50 | ||
51 | stg branch [<branch name>] | |
52 | ||
53 | This checks out the named branch and places you at the topmost applied | |
54 | StGIT patch in that branch. | |
55 | Alternately, you can create branches using only StGIT commands, which | |
56 | will automatically prepare them for use with StGIT: | |
57 | ||
58 | stg branch --create <new branch> | |
59 | ||
60 | ||
61 | Working with remote repositories | |
62 | -------------------------------- | |
d1c8fcd7 | 63 | |
c2428e5a CM |
64 | With a single command, StGIT can create and initialize a GIT repository |
65 | which mirrors a remote GIT repository. This is known as cloning. All GIT | |
66 | transports are supported. | |
67 | To clone a repository, use: | |
68 | ||
69 | stg clone <repository> <local-dir> | |
70 | ||
71 | This creates a fresh local repository, initialises a GIT database in it, | |
72 | pulls the latest version of the remote, and creates and initialises a | |
73 | 'master' branch for use with StGIT. | |
74 | At any time you can pull the latest changes from the remote repository. | |
75 | By default, StGIT pulls from the location stored in .git/branches/ | |
76 | origin, and updates the base of the current branch. | |
77 | To pull the latest changes from a remote repository, use: | |
d1c8fcd7 CM |
78 | |
79 | stg pull [<branch> or 'origin'] | |
80 | ||
c2428e5a CM |
81 | This command removes all applied StGIT patches from the current branch, |
82 | updates the branch's base commit, then attempts to re-apply the patches. | |
83 | Any merge conflicts will halt this process, allowing you to clean up the | |
84 | conflicts and continue (see below). | |
85 | If the maintainer of the remote repository includes one of your patches | |
86 | in the published repository that you pull from, StGIT can usually | |
87 | recognize that an incoming patch from the remote matches one of yours, | |
88 | and it turns your local version into an empty patch. | |
89 | To automatically delete empty patches after a pull, use: | |
d1c8fcd7 | 90 | |
c2428e5a CM |
91 | stg clean |
92 | ||
93 | As a convention, you should avoid working in the 'master' branch and use | |
94 | it only as a reference, since it reflects someone else's work. If you | |
95 | decide to publish your GIT repository, you'll want your own work | |
96 | separated into its own branch to make it convenient for others to pull | |
97 | just your patches. | |
d1c8fcd7 | 98 | |
c2428e5a CM |
99 | Getting started: creating a patch |
100 | --------------------------------- | |
101 | ||
102 | Changes to your working directory are saved in a patch. An StGIT patch | |
103 | is simply a saved set of modifications to your working directory, plus a | |
104 | saved description. To create an empty StGIT patch in the current branch: | |
d1c8fcd7 CM |
105 | |
106 | stg new <name> | |
d1c8fcd7 | 107 | |
c2428e5a | 108 | To save the changes you've made (that is, to refresh a patch), use: |
d1c8fcd7 | 109 | |
c2428e5a | 110 | stg refresh |
d1c8fcd7 | 111 | |
c2428e5a | 112 | To discard changes in your working directory, use: |
d1c8fcd7 | 113 | |
c2428e5a | 114 | git checkout -f |
d1c8fcd7 | 115 | |
c2428e5a CM |
116 | This restores your working directory to the state it was in the last |
117 | time the patch was refreshed. | |
118 | Modified files that haven't been saved via a refresh operation can be | |
119 | viewed with: | |
d1c8fcd7 | 120 | |
c2428e5a | 121 | stg status |
d1c8fcd7 | 122 | |
c2428e5a | 123 | You can view modified files that have already been saved into a patch: |
d1c8fcd7 | 124 | |
c2428e5a | 125 | stg files |
d1c8fcd7 | 126 | |
c2428e5a CM |
127 | The 'stg refresh' command automatically notes changes to files that |
128 | already exist in the working directory, but you have to tell StGIT | |
129 | explicitly if you add, remove, or rename files. | |
130 | To record the addition or deletion of files in your new patch: | |
d1c8fcd7 | 131 | |
c2428e5a CM |
132 | stg add [<file>*] |
133 | stg rm [<file>*] | |
134 | ||
135 | To record the renaming of a file in your new patch, issue both of these | |
136 | commands: | |
137 | ||
138 | stg rm <oldfilename> | |
139 | stg add <newfilename> | |
140 | ||
141 | ||
142 | Stack manipulation: managing multiple patches | |
143 | --------------------------------------------- | |
144 | ||
145 | StGIT can manage more than one patch at a time. A series of StGIT | |
146 | patches in a GIT branch are known collectively as a stack. The new patch | |
147 | you created above is now the topmost patch in your stack. You can always | |
148 | see the name of the topmost (current) patch with: | |
149 | ||
150 | stg top | |
151 | ||
152 | The topmost patch is used as the default patch for most StGIT | |
153 | operations. It is the default target of the 'stg refresh' command, for | |
154 | example. | |
155 | Patches that are pushed onto the stack are referred to as applied, and | |
156 | patches that are popped off the stack are referred to as unapplied. | |
157 | To push/pop a patch to/from a stack: | |
158 | ||
159 | stg push [--all | <name>] | |
160 | stg pop [--all] | |
d1c8fcd7 | 161 | |
c2428e5a CM |
162 | The last patch you pushed is the topmost patch. This patch is always in |
163 | the applied list; StGIT can't operate on an unapplied patch unless you | |
164 | apply it first. | |
165 | You can display the order of patches in a stack with one of these | |
166 | commands: | |
d1c8fcd7 CM |
167 | |
168 | stg series | |
169 | stg applied | |
170 | stg unapplied | |
d1c8fcd7 | 171 | |
c2428e5a CM |
172 | By default the 'stg push' command applies the first patch in the |
173 | unapplied list, but you can push any patch in the unapplied list by | |
174 | giving the name of the patch. This is useful if you want to reorder the | |
175 | patches in a stack. | |
176 | During a push operation, merge conflicts can occur (especially if you | |
177 | are changing the order of the patches in your stack). If the push causes | |
178 | merge conflicts, they need to be fixed and 'stg resolved' run (see | |
179 | below). A 'push' operation can also be reverted with 'stg push --undo'. | |
180 | A few more stack basics; to rename a patch: | |
d1c8fcd7 | 181 | |
c2428e5a | 182 | stg rename <old-name> <new-name> |
d1c8fcd7 | 183 | |
c2428e5a | 184 | To delete a patch: |
d1c8fcd7 | 185 | |
c2428e5a | 186 | stg delete <name> |
d1c8fcd7 | 187 | |
c2428e5a CM |
188 | This permanently discards the named patch. In other words, the patch no |
189 | longer appears in either the applied or unapplied lists, and cannot be | |
190 | reapplied to the series. | |
191 | You may want to make patches in your stack a permanent part of your GIT | |
192 | repository, for example if you are publishing your repository to others. | |
193 | To do this, use: | |
d1c8fcd7 | 194 | |
c2428e5a | 195 | stg commit |
d1c8fcd7 | 196 | |
c2428e5a CM |
197 | This merges all applied patches in your patch series into the GIT |
198 | repository and removes them from your stack. Use this command only if | |
199 | you want to permanently store the applied patches and no longer manage | |
200 | them with StGIT. | |
d1c8fcd7 | 201 | |
c2428e5a CM |
202 | Converting between StGIT patches and text diffs |
203 | ----------------------------------------------- | |
d1c8fcd7 | 204 | |
c2428e5a CM |
205 | As mentioned in the introduction, StGIT stores modifications to your |
206 | working tree in the form of GIT commits. This means if you want to apply | |
207 | your changes to a tree not managed by GIT, or send your changes to | |
208 | someone else in e-mail, you need to convert your StGIT patches into | |
209 | normal textual diffs that can be applied with the GNU 'patch' command. | |
210 | The 'stg diff' command is a powerful way to generate and view textual | |
211 | diffs of patches managed by StGIT. | |
212 | To view a diff of the topmost patch: | |
d1c8fcd7 | 213 | |
c2428e5a | 214 | stg diff -r / |
d1c8fcd7 | 215 | |
c2428e5a CM |
216 | Observe that this does not show any changes in the working directory |
217 | that have not been saved by a 'refresh'. To view just the changes you've | |
218 | made since the last refresh, use: | |
d1c8fcd7 | 219 | |
c2428e5a | 220 | stg diff -r /top |
d1c8fcd7 | 221 | |
c2428e5a CM |
222 | If you want to see the changes made by the patch combined with any |
223 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 224 | |
c2428e5a | 225 | stg diff -r /bottom |
d1c8fcd7 | 226 | |
c2428e5a | 227 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 228 | |
c2428e5a | 229 | stg diff -r <patch>/ |
d1c8fcd7 | 230 | |
c2428e5a CM |
231 | Use this command to view all the changes in your stack up through the |
232 | current patch: | |
233 | ||
234 | stg diff -r base | |
d1c8fcd7 | 235 | |
c2428e5a CM |
236 | The 'stg diff' command supports a number of other features that are very |
237 | useful. Be sure to take a look at the help information for this command. | |
238 | To convert your StGIT patches into patch files: | |
d1c8fcd7 | 239 | |
c2428e5a | 240 | stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 241 | |
c2428e5a CM |
242 | The 'export' command supports options to automatically number the |
243 | patches (-n) or add the '.diff' extension (-d). If you don't tell "stg | |
244 | export" where to put the patches, it will create directory named "patch- | |
245 | branchname" in your current directory, and store the patches there. | |
246 | To e-mail a patch or range of patches: | |
247 | ||
248 | stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) | |
249 | ||
250 | "stg mail" has a lot of options, so read the output of "stg mail -h" for | |
251 | more information. | |
252 | You can also import an existing GNU diff patch file as a new StGIT patch | |
253 | with a single command. "stg import" will automatically parse through the | |
254 | patch file and extract a patch description. Use: | |
255 | ||
256 | stg import [<file>] | |
d1c8fcd7 | 257 | |
c2428e5a CM |
258 | This is the equivalent of "stg new" followed by "patch -i <file>", then |
259 | "stg refresh -e". | |
260 | Sometimes the patch file won't apply cleanly. In that case, "stg import" | |
261 | will leave you with an empty StGIT patch, to which you then apply the | |
262 | patch file by hand using "patch -i" and your favorite editor. | |
d1c8fcd7 CM |
263 | To merge a GNU diff file (defaulting to the standard input) into the |
264 | topmost patch: | |
265 | ||
266 | stg fold [<file>] | |
267 | ||
c2428e5a CM |
268 | This command supports a '--threeway' option which applies the patch onto |
269 | the bottom of the topmost one and performs a three-way merge. | |
d1c8fcd7 CM |
270 | |
271 | ||
272 | Advanced Usage | |
273 | ============== | |
274 | ||
c2428e5a CM |
275 | Handling merge conflicts |
276 | ------------------------ | |
277 | ||
278 | Pushing a patch on the stack can fail if the patch cannot be applied | |
279 | cleanly. This usually happens if there are overlapping changes in the | |
280 | tree, the patch depends on another patch which is not applied, or if a | |
281 | patch was not merged upstream in the exact form it was sent. | |
282 | The 'push' operation stops after the first patch with conflicts. The | |
283 | 'status' command shows the conflict files by marking them with a 'C'. If | |
284 | the 'keeporig' options is set to 'yes' (the default), the original files | |
285 | involved in the merge operations are left in the tree as <file>.older, | |
286 | <file>.local and <file>.remote for better analysis of the conflict. If | |
287 | 'diff3' is used as the merger (the default), markers are added to the | |
288 | conflicted files as well. | |
289 | Run the 'resolved' command to mark the conflicts resolved and remove the | |
290 | temporary merge files from the working tree. Then run the 'refresh' | |
291 | command to update the StGIT patch with the modifications you made to | |
292 | resolve the conflict. | |
293 | ||
294 | ||
d1c8fcd7 CM |
295 | Configuration file |
296 | ------------------ | |
297 | ||
c2428e5a CM |
298 | StGIT tries to read the configuration options from the following files: |
299 | /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the | |
300 | options in the former files. If no file is found, the defaults are used. | |
d1c8fcd7 CM |
301 | An example configuration file with options description can be found in |
302 | the examples/ directory. Most users would probably only define the | |
303 | 'smtpserver' option used by the 'mail' command. | |
d1c8fcd7 CM |
304 | The gitmergeonefile.py script does the three-way merging on individual |
305 | files using the tool specified by the 'merger' option. The user can | |
27373fe0 CM |
306 | specify a smarter tool to be used. |
307 | ||
c2428e5a | 308 | |
27373fe0 CM |
309 | Templates |
310 | --------- | |
d1c8fcd7 | 311 | |
c2428e5a CM |
312 | The 'export' and 'mail' commands use templates for generating the patch |
313 | files or e-mails. The default templates are installed under <prefix>/ | |
314 | share/stgit/templates/ and, combined with the extra options available | |
315 | for the commands, should be enough for most users. The template format | |
316 | uses the standard Python string formatting rules. The variables | |
317 | available are shown in the the help message for the commands. | |
318 | The 'mail' command can also send an initial e-mail for which there is no | |
319 | default template. The <prefix>/share/stgit/examples/firstmail.tmpl file | |
320 | can be used as an example. | |
321 | A default description for new patches can be defined in the .git/ | |
322 | patchdescr.tmpl file. This is useful for things like signed-off-by | |
323 | lines. | |
d1c8fcd7 | 324 | |
d1c8fcd7 CM |
325 | |
326 | Merging two patches into one | |
327 | ---------------------------- | |
328 | ||
c2428e5a CM |
329 | There is no command to do this directly at the moment but one can export |
330 | the patch to be merged and use the 'stg fold' command on the generated | |
331 | diff file. Assuming that the merged patch was not already applied, the | |
332 | operation will succeed. Pushing the merged patch onto the stack will | |
333 | result in an empty patch (StGIT notifying the user) that can be safely | |
334 | deleted. | |
d1c8fcd7 CM |
335 | |
336 | ||
337 | A Bit of StGIT Patch Theory | |
338 | =========================== | |
339 | ||
340 | We assume that a patch is a diff between two nodes - bottom and top. A | |
341 | node is a commit SHA1 id or tree SHA1 id in the GIT terminology: | |
342 | ||
343 | P - patch | |
344 | N - node | |
345 | ||
346 | P = diff(Nt, Nb) | |
347 | ||
c2428e5a CM |
348 | Nb - bottom (start) node |
349 | Nt - top (end) node | |
350 | Nf - first node (for log generation) | |
d1c8fcd7 CM |
351 | |
352 | For an ordered stack of patches: | |
353 | ||
354 | P1 = diff(N1, N0) | |
355 | P2 = diff(N2, N1) | |
356 | ... | |
357 | ||
c2428e5a | 358 | |
d1c8fcd7 CM |
359 | Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb) |
360 | ||
c2428e5a CM |
361 | Ps - the big patch of the whole stack |
362 | Nsb - bottom stack node (= N0) | |
363 | Nst - top stack node (= Nn) | |
d1c8fcd7 | 364 | |
c2428e5a CM |
365 | Applying (pushing) a patch on the stack (Nst can differ from Nb) is done |
366 | by diff3 merging. The new patch becomes: | |
d1c8fcd7 CM |
367 | |
368 | P' = diff(Nt', Nb') | |
369 | Nb' = Nst | |
370 | Nt' = diff3(Nst, Nb, Nt) | |
371 | ||
372 | (note that the diff3 parameters order is: branch1, ancestor, branch2) | |
d1c8fcd7 | 373 | The above operation allows easy patch re-ordering. |
c2428e5a CM |
374 | Removing (popping) a patch from the stack is done by simply setting the |
375 | Nst to Nb. | |
376 | ||
377 | .git/ Directory Structure | |
378 | ||
d1c8fcd7 | 379 | |
c2428e5a CM |
380 | HEAD -> refs/heads/<something> |
381 | objects/ | |
382 | ??/ | |
383 | ... | |
384 | refs/ | |
385 | heads/ | |
386 | master - the master commit id | |
387 | ... | |
388 | bases/ | |
389 | master - the bottom id of the stack (to get a big diff) | |
390 | ... | |
391 | tags/ | |
392 | ... | |
393 | branches/ | |
394 | ... | |
395 | patches/ | |
396 | master/ | |
397 | applied - list of applied patches | |
398 | unapplied - list of not-yet applied patches | |
399 | current - name of the topmost patch | |
400 | patch1/ | |
401 | bottom - the bottom id of the patch | |
402 | top - the top id of the patch | |
403 | description - the patch description | |
404 | authname - author's name | |
405 | authemail - author's e-mail | |
406 | commname - committer's name | |
407 | commemail - committer's e-mail | |
408 | patch2/ | |
409 | ... | |
410 | ... | |
411 | ... |