-Stacked GIT
------------
-
StGIT is a Python application providing similar functionality to Quilt
-(i.e. pushing/poping patches to a stack) on top of GIT. These
-operations are performed using the GIT merge algorithms.
+(i.e. pushing/popping patches to/from a stack) on top of GIT. These
+operations are performed using GIT commands and the patches are stored
+as GIT commit objects, allowing easy merging of the StGIT patches into
+other repositories using standard GIT functionality.
-Note that StGIT is not an SCM interface for GIT. Use the GIT commands
-or some other tools like Cogito for this.
+Note that StGIT is not an SCM interface on top of GIT and it expects a
+previously initialised GIT repository (unless it is cloned using StGIT
+directly). For standard SCM operations, either use plain GIT commands
+or the Cogito tool but it is not recommended to mix them with the
+StGIT commands.
For the latest version see http://www.procode.org/stgit/
-
-
-Basic Operations
-----------------
-
-For a full list of commands:
-
- stg help
-
-For help on individual commands:
-
- stg <cmd> (-h | --help)
-
-To initialise a tree (the tree must have been previously initialised
-with GIT):
-
- stg init
-
-To add/delete files:
-
- stg add [<file>*]
- stg rm [<file>*]
-
-To inspect the tree status:
-
- stg status
-
-To get a diff between 2 revisions:
-
- stg diff [-r rev1[:[rev2]]]
-
-A revision name can be of the form '([patch]/[bottom | top]) | <tree-ish>'
-If the patch name is not specified but '/' is passed, the topmost
-patch is considered. If neither 'bottom' or 'top' follows the '/', the
-whole patch diff is displayed (this does not include the local
-changes).
-
-Note than when the first patch is pushed to the stack, the current
-HEAD is saved in the .git/refs/heads/base file for easy reference.
-
-To create/delete a patch:
-
- stg new <name>
- stg delete [<name or topmost>]
-
-The 'new' command also sets the topmost patch to the newly created
-one.
-
-To push/pop a patch to/from the stack:
-
- stg push [<name or first unapplied>]
- stg pop [<name or topmost>]
-
-Note that the 'push' command can apply any patch in the unapplied
-list. This is useful if you want to reorder the patches.
-
-To add the patch changes to the tree:
-
- stg refresh
-
-To inspect the patches applied:
-
- stg series
- stg applied
- stg unapplied
- stg top
-
-To export a patch series:
-
- stg export [<dir-name or 'patches'>]
-
-The 'export' command supports options to automatically number the
-patches (-n) or add the '.diff' extension (-d).
-
-StGIT does not yet provide support for cloning or pulling changes from
-a different repository. Until this becomes available, run the
-following commands:
-
- stg pop -a
- your-git-script-for-pulling-and-merging
- stg push -a
-
-You can also look in the TODO file for what's planned to be
-implemented in the future.
-
-
-Directory Structure
--------------------
-
-.git/
- objects/
- ??/
-
-refs/
- heads/
- master - the master commit id
- ...
- bases/
- master - the bottom id of the stack (to get a big diff)
- ...
- tags/
- ...
- branches/
- ...
- patches/
- master/
- applied - list of applied patches
- unapplied - list of not-yet applied patches
- current - name of the topmost patch
- patch1/
- first - the initial id of the patch (used for log)
- bottom - the bottom id of the patch
- top - the top id of the patch
- patch2/
- ...
- ...
-
-HEAD -> refs/heads/<something>
-
-
-A Bit of StGIT Patch Theory
----------------------------
-
-We assume that a patch is a diff between two nodes - bottom and top. A
-node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
-
-P - patch
-N - node
-
-P = diff(Nt, Nb)
-
- Nb - bottom (start) node
- Nt - top (end) node
- Nf - first node (for log generation)
-
-For an ordered stack of patches:
-
-P1 = diff(N1, N0)
-P2 = diff(N2, N1)
-...
-
-Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
-
- Ps - the big patch of the whole stack
- Nsb - bottom stack node (= N0)
- Nst - top stack node (= Nn)
-
-Applying (pushing) a patch on the stack (Nst can differ from Nb) is
-done by diff3 merging. The new patch becomes:
-
-P' = diff(Nt', Nb')
-Nb' = Nst
-Nt' = diff3(Nst, Nb, Nt)
-
-(note that the diff3 parameters order is: branch1, ancestor, branch2)
-
-The above operation allows easy patch re-ordering.
-
-Removing (popping) a patch from the stack is done by simply setting
-the Nst to Nb.
+For a tutorial see http://wiki.procode.org/cgi-bin/wiki.cgi/StGIT_Tutorial
~mdw / stgit / blobdiff