| 1 | Stacked GIT |
| 2 | ----------- |
| 3 | |
| 4 | StGIT is a Python application providing similar functionality to Quilt |
| 5 | (i.e. pushing/poping patches to a stack) on top of GIT. These |
| 6 | operations are performed using the GIT merge algorithms. |
| 7 | |
| 8 | Note that StGIT is not an SCM interface for GIT. Use the GIT commands |
| 9 | or some other tools like Cogito for this. |
| 10 | |
| 11 | For the latest version see http://www.procode.org/stgit/ |
| 12 | |
| 13 | |
| 14 | Basic Operations |
| 15 | ---------------- |
| 16 | |
| 17 | For a full list of commands: |
| 18 | |
| 19 | stg help |
| 20 | |
| 21 | For help on individual commands: |
| 22 | |
| 23 | stg <cmd> (-h | --help) |
| 24 | |
| 25 | To initialise a tree (the tree must have been previously initialised |
| 26 | with GIT): |
| 27 | |
| 28 | stg init |
| 29 | |
| 30 | To add/delete files: |
| 31 | |
| 32 | stg add [<file>*] |
| 33 | stg rm [<file>*] |
| 34 | |
| 35 | To inspect the tree status: |
| 36 | |
| 37 | stg status |
| 38 | |
| 39 | To get a diff between 2 revisions: |
| 40 | |
| 41 | stg diff [-r rev1[:[rev2]]] |
| 42 | |
| 43 | A revision name can be of the form '([patch]/[bottom | top]) | <tree-ish>' |
| 44 | If the patch name is not specified but '/' is passed, the topmost |
| 45 | patch is considered. If neither 'bottom' or 'top' follows the '/', the |
| 46 | whole patch diff is displayed (this does not include the local |
| 47 | changes). |
| 48 | |
| 49 | Note than when the first patch is pushed to the stack, the current |
| 50 | HEAD is saved in the .git/refs/heads/base file for easy reference. |
| 51 | |
| 52 | To create/delete a patch: |
| 53 | |
| 54 | stg new <name> |
| 55 | stg delete [<name or topmost>] |
| 56 | |
| 57 | The 'new' command also sets the topmost patch to the newly created |
| 58 | one. |
| 59 | |
| 60 | To push/pop a patch to/from the stack: |
| 61 | |
| 62 | stg push [<name or first unapplied>] |
| 63 | stg pop [<name or topmost>] |
| 64 | |
| 65 | Note that the 'push' command can apply any patch in the unapplied |
| 66 | list. This is useful if you want to reorder the patches. |
| 67 | |
| 68 | To add the patch changes to the tree: |
| 69 | |
| 70 | stg refresh |
| 71 | |
| 72 | To inspect the patches applied: |
| 73 | |
| 74 | stg series |
| 75 | stg applied |
| 76 | stg unapplied |
| 77 | stg top |
| 78 | |
| 79 | To export a patch series: |
| 80 | |
| 81 | stg export [<dir-name or 'patches'>] |
| 82 | |
| 83 | The 'export' command supports options to automatically number the |
| 84 | patches (-n) or add the '.diff' extension (-d). |
| 85 | |
| 86 | StGIT does not yet provide support for cloning or pulling changes from |
| 87 | a different repository. Until this becomes available, run the |
| 88 | following commands: |
| 89 | |
| 90 | stg pop -a |
| 91 | your-git-script-for-pulling-and-merging |
| 92 | stg push -a |
| 93 | |
| 94 | You can also look in the TODO file for what's planned to be |
| 95 | implemented in the future. |
| 96 | |
| 97 | |
| 98 | Directory Structure |
| 99 | ------------------- |
| 100 | |
| 101 | .git/ |
| 102 | objects/ |
| 103 | ??/ |
| 104 | |
| 105 | refs/ |
| 106 | heads/ |
| 107 | master - the master commit id |
| 108 | ... |
| 109 | bases/ |
| 110 | master - the bottom id of the stack (to get a big diff) |
| 111 | ... |
| 112 | tags/ |
| 113 | ... |
| 114 | branches/ |
| 115 | ... |
| 116 | patches/ |
| 117 | master/ |
| 118 | applied - list of applied patches |
| 119 | unapplied - list of not-yet applied patches |
| 120 | current - name of the topmost patch |
| 121 | patch1/ |
| 122 | first - the initial id of the patch (used for log) |
| 123 | bottom - the bottom id of the patch |
| 124 | top - the top id of the patch |
| 125 | patch2/ |
| 126 | ... |
| 127 | ... |
| 128 | |
| 129 | HEAD -> refs/heads/<something> |
| 130 | |
| 131 | |
| 132 | A Bit of StGIT Patch Theory |
| 133 | --------------------------- |
| 134 | |
| 135 | We assume that a patch is a diff between two nodes - bottom and top. A |
| 136 | node is a commit SHA1 id or tree SHA1 id in the GIT terminology: |
| 137 | |
| 138 | P - patch |
| 139 | N - node |
| 140 | |
| 141 | P = diff(Nt, Nb) |
| 142 | |
| 143 | Nb - bottom (start) node |
| 144 | Nt - top (end) node |
| 145 | Nf - first node (for log generation) |
| 146 | |
| 147 | For an ordered stack of patches: |
| 148 | |
| 149 | P1 = diff(N1, N0) |
| 150 | P2 = diff(N2, N1) |
| 151 | ... |
| 152 | |
| 153 | Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb) |
| 154 | |
| 155 | Ps - the big patch of the whole stack |
| 156 | Nsb - bottom stack node (= N0) |
| 157 | Nst - top stack node (= Nn) |
| 158 | |
| 159 | Applying (pushing) a patch on the stack (Nst can differ from Nb) is |
| 160 | done by diff3 merging. The new patch becomes: |
| 161 | |
| 162 | P' = diff(Nt', Nb') |
| 163 | Nb' = Nst |
| 164 | Nt' = diff3(Nst, Nb, Nt) |
| 165 | |
| 166 | (note that the diff3 parameters order is: branch1, ancestor, branch2) |
| 167 | |
| 168 | The above operation allows easy patch re-ordering. |
| 169 | |
| 170 | Removing (popping) a patch from the stack is done by simply setting |
| 171 | the Nst to Nb. |