mdw@git.distorted.org.uk Git - stgit/blob - README

   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.