| 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 |
| 182 | specify a smarter tool to be used. |
| 183 | |
| 184 | Templates |
| 185 | --------- |
| 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 |
| 201 | signed-off-by lines. |
| 202 | |
| 203 | Dealing with conflicts |
| 204 | ---------------------- |
| 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. |