Commit | Line | Data |
---|---|---|
d1c8fcd7 CM |
1 | StGIT Tutorial |
2 | ||
3 | ||
4 | Introduction | |
5 | ============ | |
6 | ||
7 | StGIT is a Python application providing similar functionality to Quilt | |
8 | (i.e. pushing/popping patches to/from a stack) on top of GIT. These | |
9 | operations are performed using GIT commands and the patches are stored | |
10 | as GIT commit objects, allowing easy merging of the StGIT patches into | |
11 | other repositories using standard GIT functionality. | |
12 | ||
13 | Note that StGIT is not an SCM interface on top of GIT and it expects a | |
14 | previously initialised GIT repository (unless it is cloned using StGIT | |
15 | directly). For standard SCM operations, either use plain GIT commands | |
16 | or the Cogito tool but it is not recommended to mix them with the | |
17 | StGIT commands. | |
18 | ||
19 | For the latest version see http://www.procode.org/stgit/ | |
20 | ||
21 | ||
22 | Basic Operations | |
23 | ================ | |
24 | ||
25 | See the help on individual commands for the full set of options. | |
26 | ||
27 | Help | |
28 | ---- | |
29 | ||
30 | For a full list of commands: | |
31 | ||
32 | stg help | |
33 | ||
34 | For help on individual commands: | |
35 | ||
36 | stg <cmd> (-h | --help) | |
37 | ||
38 | Repository initialisation/updating | |
39 | ---------------------------------- | |
40 | ||
41 | To clone a repository (all the GIT repository types are accepted): | |
42 | ||
43 | stg clone <repository> <local-dir> | |
44 | ||
45 | To initialise an existing GIT repository to be used with StGIT (not | |
46 | needed if the cloning was done using StGIT): | |
47 | ||
48 | stg init | |
49 | ||
50 | For people switching between multiple branches in the same repository, | |
51 | the 'init' command needs to be run for all the branches intended to be | |
52 | used with StGIT. | |
53 | ||
54 | To pull the latest changes from the remote repository (defaulting to | |
55 | the value in .git/branches/origin): | |
56 | ||
57 | stg pull [<branch> or 'origin'] | |
58 | ||
59 | The 'pull' command takes care of updating all the patches in the stack | |
60 | so that they apply cleanly (the user is notified of the possible | |
61 | conflicts). | |
62 | ||
63 | Stack manipulation | |
64 | ------------------ | |
65 | ||
66 | To create/delete a patch: | |
67 | ||
68 | stg new <name> | |
69 | stg delete <name> | |
70 | ||
71 | The 'new' command also sets the topmost patch to the newly created | |
72 | one. | |
73 | ||
74 | To automatically delete the empty patches: | |
75 | ||
76 | stg clean | |
77 | ||
78 | To push/pop a patch to/from the stack: | |
79 | ||
80 | stg push [--all | <name or first unapplied>] | |
81 | stg pop [--all | <name or topmost>] | |
82 | ||
83 | Note that the 'push' command can apply any patch in the unapplied | |
84 | list. This is useful if one wants to reorder the patches. If there are | |
85 | conflicts, they need to be fixed and 'stg resolved' run. The 'push' | |
86 | operation can also be reverted with 'stg push --undo'. | |
87 | ||
88 | To rename a patch: | |
89 | ||
90 | stg rename <old-name> <new-name> | |
91 | ||
92 | To import an existing GNU diff patch file (defaulting to the standard | |
93 | input): | |
94 | ||
95 | stg import [<file>] | |
96 | ||
97 | To inspect the stack status: | |
98 | ||
99 | stg series | |
100 | stg applied | |
101 | stg unapplied | |
102 | stg top | |
103 | ||
104 | To export a patch series (or a range of patches): | |
105 | ||
106 | stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>] | |
107 | ||
108 | The 'export' command supports options to automatically number the | |
109 | patches (-n) or add the '.diff' extension (-d). | |
110 | ||
111 | To e-mail a patch or range of patches: | |
112 | ||
113 | stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) | |
114 | ||
115 | Changes to the topmost patch | |
116 | ---------------------------- | |
117 | ||
118 | Any modified file already under revision control will automatically be | |
119 | included in the topmost patch. | |
120 | ||
121 | To add/delete files to/from the topmost patch: | |
122 | ||
123 | stg add [<file>*] | |
124 | stg rm [<file>*] | |
125 | ||
126 | To inspect the tree status: | |
127 | ||
128 | stg status | |
129 | ||
130 | To get a diff between 2 revisions: | |
131 | ||
132 | stg diff [-r rev1[:[rev2]]] | |
133 | ||
134 | A revision name can be of the form '([patch]/[bottom | top]) | base | | |
135 | <tree-ish>' If the patch name is not specified but '/' is passed, the | |
136 | topmost patch is used. If neither 'bottom' nor 'top' follows the '/', | |
137 | the whole patch diff is displayed (this does not include the local | |
138 | changes). | |
139 | ||
140 | Note than when the first patch is pushed on the stack, the current | |
141 | HEAD is saved in the .git/refs/heads/base file for easy reference to | |
142 | the base of the stack. | |
143 | ||
144 | To save the tree changes to the current patch and the GIT repository: | |
145 | ||
146 | stg refresh | |
147 | ||
148 | The 'refresh' command also allows the modification of the patch | |
149 | description and the author/maintainer information. | |
150 | ||
151 | To display the files modified by a patch (defaulting to the topmost | |
152 | one): | |
153 | ||
154 | stg files [<patch>] | |
155 | ||
156 | To merge a GNU diff file (defaulting to the standard input) into the | |
157 | topmost patch: | |
158 | ||
159 | stg fold [<file>] | |
160 | ||
161 | This command supports a '--threeway' option which applies the patch | |
162 | onto the bottom of the topmost one and performs a three-way merge. | |
163 | ||
164 | ||
165 | Advanced Usage | |
166 | ============== | |
167 | ||
168 | Configuration file | |
169 | ------------------ | |
170 | ||
171 | StGIT tries to read the configuration options from the following | |
172 | files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides | |
173 | the options in the former files. If no file is found, the defaults are | |
174 | used. | |
175 | ||
176 | An example configuration file with options description can be found in | |
177 | the examples/ directory. Most users would probably only define the | |
178 | 'smtpserver' option used by the 'mail' command. | |
179 | ||
180 | The gitmergeonefile.py script does the three-way merging on individual | |
181 | files using the tool specified by the 'merger' option. The user can | |
27373fe0 CM |
182 | specify a smarter tool to be used. |
183 | ||
184 | Templates | |
185 | --------- | |
d1c8fcd7 CM |
186 | |
187 | The 'export' and 'mail' commands use templates for generating the | |
188 | patch files or e-mails. The default templates are installed under | |
189 | <prefix>/share/stgit/templates/ and, combined with the extra options | |
190 | available for the commands, should be enough for most users. The | |
191 | template format uses the standard Python string formatting rules. The | |
192 | variables available are shown in the the help message for the | |
193 | commands. | |
194 | ||
195 | The 'mail' command can also send an initial e-mail for which there is | |
196 | no default template. The <prefix>/share/stgit/examples/firstmail.tmpl | |
197 | file can be used as an example. | |
198 | ||
199 | A default description for new patches can be defined in the | |
200 | .git/patchdescr.tmpl file. This is useful for things like | |
27373fe0 CM |
201 | signed-off-by lines. |
202 | ||
203 | Dealing with conflicts | |
204 | ---------------------- | |
d1c8fcd7 CM |
205 | |
206 | Pushing a patch on the stack can fail if the patch cannot be applied | |
207 | cleanly. This usually happens if there are overlapping changes in the | |
208 | tree, the patch depends on other patch which is not applied or if a | |
209 | patch was not merged upstream in the exact form it was sent. | |
210 | ||
211 | The 'push' operation will stop after the first patch with | |
212 | conflicts. The 'status' command shows the conflict files by marking | |
213 | them with a 'C'. If the 'keeporig' options is set to 'yes' (the | |
214 | default), the original files involved in the merge operations are left | |
215 | in the tree as <file>.older, <file>.local and <file>.remote for a | |
216 | better analysis by the user. If 'diff3' is used as the merger (the | |
217 | default), conflict markers can be found in the corresponding files as | |
218 | well. | |
219 | ||
220 | Once the conflict is fixed, the 'resolved' command has to be run to | |
221 | clear the conflict state. This command also removes the original files | |
222 | involved in the merge for a given file. | |
223 | ||
224 | Merging two patches into one | |
225 | ---------------------------- | |
226 | ||
227 | There is no command to do this directly at the moment but one can | |
228 | export the patch to be merged and use the 'stg fold' command on the | |
229 | generated diff file. Assuming that the merged patch was not already | |
230 | applied, the operation will succeed. Pushing the merged patch onto the | |
231 | stack will result in an empty patch (StGIT notifying the user) that | |
232 | can be safely deleted. | |
233 | ||
234 | ||
235 | .git/ Directory Structure | |
236 | ========================= | |
237 | ||
238 | HEAD -> refs/heads/<something> | |
239 | objects/ | |
240 | ??/ | |
241 | ... | |
242 | refs/ | |
243 | heads/ | |
244 | master - the master commit id | |
245 | ... | |
246 | bases/ | |
247 | master - the bottom id of the stack (to get a big diff) | |
248 | ... | |
249 | tags/ | |
250 | ... | |
251 | branches/ | |
252 | ... | |
253 | patches/ | |
254 | master/ | |
255 | applied - list of applied patches | |
256 | unapplied - list of not-yet applied patches | |
257 | current - name of the topmost patch | |
258 | patch1/ | |
259 | bottom - the bottom id of the patch | |
260 | top - the top id of the patch | |
261 | description - the patch description | |
262 | authname - author's name | |
263 | authemail - author's e-mail | |
264 | commname - committer's name | |
265 | commemail - committer's e-mail | |
266 | patch2/ | |
267 | ... | |
268 | ... | |
269 | ... | |
270 | ||
271 | ||
272 | A Bit of StGIT Patch Theory | |
273 | =========================== | |
274 | ||
275 | We assume that a patch is a diff between two nodes - bottom and top. A | |
276 | node is a commit SHA1 id or tree SHA1 id in the GIT terminology: | |
277 | ||
278 | P - patch | |
279 | N - node | |
280 | ||
281 | P = diff(Nt, Nb) | |
282 | ||
283 | Nb - bottom (start) node | |
284 | Nt - top (end) node | |
285 | Nf - first node (for log generation) | |
286 | ||
287 | For an ordered stack of patches: | |
288 | ||
289 | P1 = diff(N1, N0) | |
290 | P2 = diff(N2, N1) | |
291 | ... | |
292 | ||
293 | Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb) | |
294 | ||
295 | Ps - the big patch of the whole stack | |
296 | Nsb - bottom stack node (= N0) | |
297 | Nst - top stack node (= Nn) | |
298 | ||
299 | Applying (pushing) a patch on the stack (Nst can differ from Nb) is | |
300 | done by diff3 merging. The new patch becomes: | |
301 | ||
302 | P' = diff(Nt', Nb') | |
303 | Nb' = Nst | |
304 | Nt' = diff3(Nst, Nb, Nt) | |
305 | ||
306 | (note that the diff3 parameters order is: branch1, ancestor, branch2) | |
307 | ||
308 | The above operation allows easy patch re-ordering. | |
309 | ||
310 | Removing (popping) a patch from the stack is done by simply setting | |
311 | the Nst to Nb. |