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