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