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