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