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 | |
625e8de7 KH |
181 | below). A 'push' operation can also be reverted with 'stg undo' (you |
182 | will need to give it the --hard flag, since the conflicting push will | |
183 | have left your work tree dirty). | |
c2428e5a | 184 | A few more stack basics; to rename a patch: |
d1c8fcd7 | 185 | |
c2428e5a | 186 | stg rename <old-name> <new-name> |
d1c8fcd7 | 187 | |
c2428e5a | 188 | To delete a patch: |
d1c8fcd7 | 189 | |
c2428e5a | 190 | stg delete <name> |
d1c8fcd7 | 191 | |
c2428e5a CM |
192 | This permanently discards the named patch. In other words, the patch no |
193 | longer appears in either the applied or unapplied lists, and cannot be | |
194 | reapplied to the series. | |
195 | You may want to make patches in your stack a permanent part of your GIT | |
196 | repository, for example if you are publishing your repository to others. | |
197 | To do this, use: | |
d1c8fcd7 | 198 | |
c2428e5a | 199 | stg commit |
d1c8fcd7 | 200 | |
c2428e5a CM |
201 | This merges all applied patches in your patch series into the GIT |
202 | repository and removes them from your stack. Use this command only if | |
203 | you want to permanently store the applied patches and no longer manage | |
204 | them with StGIT. | |
d1c8fcd7 | 205 | |
c2428e5a CM |
206 | Converting between StGIT patches and text diffs |
207 | ----------------------------------------------- | |
d1c8fcd7 | 208 | |
c2428e5a CM |
209 | As mentioned in the introduction, StGIT stores modifications to your |
210 | working tree in the form of GIT commits. This means if you want to apply | |
211 | your changes to a tree not managed by GIT, or send your changes to | |
212 | someone else in e-mail, you need to convert your StGIT patches into | |
213 | normal textual diffs that can be applied with the GNU 'patch' command. | |
214 | The 'stg diff' command is a powerful way to generate and view textual | |
215 | diffs of patches managed by StGIT. | |
216 | To view a diff of the topmost patch: | |
d1c8fcd7 | 217 | |
c2428e5a | 218 | stg diff -r / |
d1c8fcd7 | 219 | |
c2428e5a CM |
220 | Observe that this does not show any changes in the working directory |
221 | that have not been saved by a 'refresh'. To view just the changes you've | |
222 | made since the last refresh, use: | |
d1c8fcd7 | 223 | |
c2428e5a | 224 | stg diff -r /top |
d1c8fcd7 | 225 | |
c2428e5a CM |
226 | If you want to see the changes made by the patch combined with any |
227 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 228 | |
c2428e5a | 229 | stg diff -r /bottom |
d1c8fcd7 | 230 | |
c2428e5a | 231 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 232 | |
c2428e5a | 233 | stg diff -r <patch>/ |
d1c8fcd7 | 234 | |
c2428e5a CM |
235 | Use this command to view all the changes in your stack up through the |
236 | current patch: | |
237 | ||
238 | stg diff -r base | |
d1c8fcd7 | 239 | |
c2428e5a CM |
240 | The 'stg diff' command supports a number of other features that are very |
241 | useful. Be sure to take a look at the help information for this command. | |
242 | To convert your StGIT patches into patch files: | |
d1c8fcd7 | 243 | |
c2428e5a | 244 | stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 245 | |
c2428e5a CM |
246 | The 'export' command supports options to automatically number the |
247 | patches (-n) or add the '.diff' extension (-d). If you don't tell "stg | |
248 | export" where to put the patches, it will create directory named "patch- | |
249 | branchname" in your current directory, and store the patches there. | |
250 | To e-mail a patch or range of patches: | |
251 | ||
252 | stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) | |
253 | ||
254 | "stg mail" has a lot of options, so read the output of "stg mail -h" for | |
255 | more information. | |
256 | You can also import an existing GNU diff patch file as a new StGIT patch | |
257 | with a single command. "stg import" will automatically parse through the | |
258 | patch file and extract a patch description. Use: | |
259 | ||
260 | stg import [<file>] | |
d1c8fcd7 | 261 | |
c2428e5a CM |
262 | This is the equivalent of "stg new" followed by "patch -i <file>", then |
263 | "stg refresh -e". | |
264 | Sometimes the patch file won't apply cleanly. In that case, "stg import" | |
265 | will leave you with an empty StGIT patch, to which you then apply the | |
266 | patch file by hand using "patch -i" and your favorite editor. | |
d1c8fcd7 CM |
267 | To merge a GNU diff file (defaulting to the standard input) into the |
268 | topmost patch: | |
269 | ||
270 | stg fold [<file>] | |
271 | ||
c2428e5a CM |
272 | This command supports a '--threeway' option which applies the patch onto |
273 | the bottom of the topmost one and performs a three-way merge. | |
d1c8fcd7 CM |
274 | |
275 | ||
276 | Advanced Usage | |
277 | ============== | |
278 | ||
c2428e5a CM |
279 | Handling merge conflicts |
280 | ------------------------ | |
281 | ||
282 | Pushing a patch on the stack can fail if the patch cannot be applied | |
283 | cleanly. This usually happens if there are overlapping changes in the | |
284 | tree, the patch depends on another patch which is not applied, or if a | |
285 | patch was not merged upstream in the exact form it was sent. | |
286 | The 'push' operation stops after the first patch with conflicts. The | |
287 | 'status' command shows the conflict files by marking them with a 'C'. If | |
288 | the 'keeporig' options is set to 'yes' (the default), the original files | |
289 | involved in the merge operations are left in the tree as <file>.older, | |
290 | <file>.local and <file>.remote for better analysis of the conflict. If | |
291 | 'diff3' is used as the merger (the default), markers are added to the | |
292 | conflicted files as well. | |
293 | Run the 'resolved' command to mark the conflicts resolved and remove the | |
294 | temporary merge files from the working tree. Then run the 'refresh' | |
295 | command to update the StGIT patch with the modifications you made to | |
296 | resolve the conflict. | |
297 | ||
298 | ||
d1c8fcd7 CM |
299 | Configuration file |
300 | ------------------ | |
301 | ||
c2428e5a CM |
302 | StGIT tries to read the configuration options from the following files: |
303 | /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the | |
304 | options in the former files. If no file is found, the defaults are used. | |
d1c8fcd7 CM |
305 | An example configuration file with options description can be found in |
306 | the examples/ directory. Most users would probably only define the | |
307 | 'smtpserver' option used by the 'mail' command. | |
d1c8fcd7 CM |
308 | The gitmergeonefile.py script does the three-way merging on individual |
309 | files using the tool specified by the 'merger' option. The user can | |
27373fe0 CM |
310 | specify a smarter tool to be used. |
311 | ||
c2428e5a | 312 | |
27373fe0 CM |
313 | Templates |
314 | --------- | |
d1c8fcd7 | 315 | |
c2428e5a CM |
316 | The 'export' and 'mail' commands use templates for generating the patch |
317 | files or e-mails. The default templates are installed under <prefix>/ | |
318 | share/stgit/templates/ and, combined with the extra options available | |
319 | for the commands, should be enough for most users. The template format | |
320 | uses the standard Python string formatting rules. The variables | |
321 | available are shown in the the help message for the commands. | |
322 | The 'mail' command can also send an initial e-mail for which there is no | |
323 | default template. The <prefix>/share/stgit/examples/firstmail.tmpl file | |
324 | can be used as an example. | |
325 | A default description for new patches can be defined in the .git/ | |
326 | patchdescr.tmpl file. This is useful for things like signed-off-by | |
327 | lines. | |
d1c8fcd7 | 328 | |
d1c8fcd7 CM |
329 | |
330 | Merging two patches into one | |
331 | ---------------------------- | |
332 | ||
c2428e5a CM |
333 | There is no command to do this directly at the moment but one can export |
334 | the patch to be merged and use the 'stg fold' command on the generated | |
335 | diff file. Assuming that the merged patch was not already applied, the | |
336 | operation will succeed. Pushing the merged patch onto the stack will | |
337 | result in an empty patch (StGIT notifying the user) that can be safely | |
338 | deleted. | |
d1c8fcd7 CM |
339 | |
340 | ||
4625b604 PR |
341 | Technical Information |
342 | ===================== | |
343 | ||
344 | A bit of StGIT patch theory | |
345 | --------------------------- | |
d1c8fcd7 CM |
346 | |
347 | We assume that a patch is a diff between two nodes - bottom and top. A | |
348 | node is a commit SHA1 id or tree SHA1 id in the GIT terminology: | |
349 | ||
350 | P - patch | |
351 | N - node | |
352 | ||
353 | P = diff(Nt, Nb) | |
354 | ||
c2428e5a CM |
355 | Nb - bottom (start) node |
356 | Nt - top (end) node | |
357 | Nf - first node (for log generation) | |
d1c8fcd7 CM |
358 | |
359 | For an ordered stack of patches: | |
360 | ||
361 | P1 = diff(N1, N0) | |
362 | P2 = diff(N2, N1) | |
363 | ... | |
364 | ||
c2428e5a | 365 | |
d1c8fcd7 CM |
366 | Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb) |
367 | ||
c2428e5a CM |
368 | Ps - the big patch of the whole stack |
369 | Nsb - bottom stack node (= N0) | |
370 | Nst - top stack node (= Nn) | |
d1c8fcd7 | 371 | |
c2428e5a CM |
372 | Applying (pushing) a patch on the stack (Nst can differ from Nb) is done |
373 | by diff3 merging. The new patch becomes: | |
d1c8fcd7 CM |
374 | |
375 | P' = diff(Nt', Nb') | |
376 | Nb' = Nst | |
377 | Nt' = diff3(Nst, Nb, Nt) | |
378 | ||
379 | (note that the diff3 parameters order is: branch1, ancestor, branch2) | |
d1c8fcd7 | 380 | The above operation allows easy patch re-ordering. |
c2428e5a CM |
381 | Removing (popping) a patch from the stack is done by simply setting the |
382 | Nst to Nb. | |
383 | ||
c2428e5a | 384 | |
4625b604 PR |
385 | Layout of the .git directory |
386 | ---------------------------- | |
d1c8fcd7 | 387 | |
c2428e5a CM |
388 | HEAD -> refs/heads/<something> |
389 | objects/ | |
390 | ??/ | |
391 | ... | |
392 | refs/ | |
393 | heads/ | |
394 | master - the master commit id | |
395 | ... | |
c2428e5a CM |
396 | tags/ |
397 | ... | |
398 | branches/ | |
399 | ... | |
400 | patches/ | |
401 | master/ | |
402 | applied - list of applied patches | |
403 | unapplied - list of not-yet applied patches | |
404 | current - name of the topmost patch | |
405 | patch1/ | |
406 | bottom - the bottom id of the patch | |
407 | top - the top id of the patch | |
408 | description - the patch description | |
409 | authname - author's name | |
410 | authemail - author's e-mail | |
411 | commname - committer's name | |
412 | commemail - committer's e-mail | |
413 | patch2/ | |
414 | ... | |
415 | ... | |
416 | ... |