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:
+See the help on individual commands for the full set of options.
+
+Help
+----
+
+ For a full list of commands:
stg help
-For help on individual commands:
+ For help on individual commands:
stg <cmd> (-h | --help)
-To initialise a tree (the tree must have been previously initialised
-with GIT):
+Repository initialisation/updating
+----------------------------------
- stg init
+ To clone a repository (all the GIT repository types are accepted):
-To add/delete files:
+ stg clone <repository> <local-dir>
- stg add [<file>*]
- stg rm [<file>*]
+ To initialise an existing GIT repository to be used with StGIT (not
+ needed if the cloning was done using StGIT):
-To inspect the tree status:
+ stg init
- stg status
+ For people switching between multiple branches in the same
+ repository, the 'init' command needs to be run for all the branches
+ intended to be used with StGIT.
-To get a diff between 2 revisions:
+ To pull the latest changes from the remote repository (defaulting to
+ the value in .git/branches/origin):
- stg diff [-r rev1[:[rev2]]]
+ stg pull [<branch> or 'origin']
-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).
+ The 'pull' command takes care of updating all the patches in the
+ stack so that they apply cleanly (the user is notified of the
+ possible conflicts).
-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.
+Stack manipulation
+------------------
-To create/delete a patch:
+ To create/delete a patch:
stg new <name>
- stg delete [<name or topmost>]
+ stg delete <name>
-The 'new' command also sets the topmost patch to the newly created
-one.
+ The 'new' command also sets the topmost patch to the newly created
+ one.
-To push/pop a patch to/from the stack:
+ To automatically delete the empty patches:
- stg push [<name or first unapplied>]
- stg pop [<name or topmost>]
+ stg clean
-Note that the 'push' command can apply any patch in the unapplied
-list. This is useful if you want to reorder the patches.
+ To push/pop a patch to/from the stack:
-To add the patch changes to the tree:
+ stg push [--all | <name or first unapplied>]
+ stg pop [--all | <name or topmost>]
- stg refresh
+ Note that the 'push' command can apply any patch in the unapplied
+ list. This is useful if one wants to reorder the patches. If there
+ are conflicts, they need to be fixed and 'stg resolved' run. The
+ 'push' operation can also be reverted with 'stg push --undo'.
+
+ To rename a patch:
+
+ stg rename <old-name> <new-name>
-To inspect the patches applied:
+ To import an existing GNU diff patch file (defaulting to the
+ standard input):
+
+ stg import [<file>]
+
+ To inspect the stack status:
stg series
stg applied
stg unapplied
stg top
-To export a patch series:
+ To export a patch series (or a range of patches):
+
+ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>]
- stg export [<dir-name or 'patches'>]
+ The 'export' command supports options to automatically number the
+ patches (-n) or add the '.diff' extension (-d).
-The 'export' command supports options to automatically number the
-patches (-n) or add the '.diff' extension (-d).
+ To e-mail a patch or range of patches:
-StGIT does not yet provide support for cloning or pulling changes from
-a different repository. Until this becomes available, run the
-following commands:
+ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
- stg pop -a
- your-git-script-for-pulling-and-merging
- stg push -a
+Changes to the topmost patch
+----------------------------
-You can also look in the TODO file for what's planned to be
-implemented in the future.
+ Any modified file already under revision control will automatically
+ be included in the topmost patch.
+ To add/delete files to/from the topmost patch:
-Directory Structure
--------------------
+ 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]) | base
+ | <tree-ish>' If the patch name is not specified but '/' is passed,
+ the topmost patch is used. If neither 'bottom' nor 'top' follows the
+ '/', the whole patch diff is displayed (this does not include the
+ local changes).
+
+ Note than when the first patch is pushed on the stack, the current
+ HEAD is saved in the .git/refs/heads/base file for easy reference to
+ the base of the stack.
+
+ To save the tree changes to the current patch and the GIT
+ repository:
+
+ stg refresh
-.git/
- objects/
- ??/
+ The 'refresh' command also allows the modification of the patch
+ description and the author/maintainer information.
+ To display the files modified by a patch (defaulting to the topmost
+ one):
+
+ stg files [<patch>]
+
+ To merge a GNU diff file (defaulting to the standard input) into the
+ topmost patch:
+
+ stg fold [<file>]
+
+ This command supports a '--threeway' option which applies the patch
+ onto the bottom of the topmost one and performs a three-way merge.
+
+
+Advanced Usage
+==============
+
+Configuration file
+------------------
+
+StGIT tries to read the configuration options from the following
+files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides
+the options in the former files. If no file is found, the defaults are
+used.
+
+An example configuration file with options description can be found in
+the examples/ directory. Most users would probably only define the
+'smtpserver' option used by the 'mail' command.
+
+The gitmergeonefile.py script does the three-way merging on individual
+files using the tool specified by the 'merger' option. The user can
+specify a smarter tool to be used.
+
+Templates
+---------
+
+The 'export' and 'mail' commands use templates for generating the
+patch files or e-mails. The default templates are installed under
+<prefix>/share/stgit/templates/ and, combined with the extra options
+available for the commands, should be enough for most users. The
+template format uses the standard Python string formatting rules. The
+variables available are shown in the the help message for the
+commands.
+
+The 'mail' command can also send an initial e-mail for which there is
+no default template. The <prefix>/share/stgit/examples/firstmail.tmpl
+file can be used as an example.
+
+A default description for new patches can be defined in the
+.git/patchdescr.tmpl file. This is useful for things like
+signed-off-by lines.
+
+Dealing with conflicts
+----------------------
+
+Pushing a patch on the stack can fail if the patch cannot be applied
+cleanly. This usually happens if there are overlapping changes in the
+tree, the patch depends on other patch which is not applied or if a
+patch was not merged upstream in the exact form it was sent.
+
+The 'push' operation will stop after the first patch with
+conflicts. The 'status' command shows the conflict files by marking
+them with a 'C'. If the 'keeporig' options is set to 'yes' (the
+default), the original files involved in the merge operations are left
+in the tree as <file>.older, <file>.local and <file>.remote for a
+better analysis by the user. If 'diff3' is used as the merger (the
+default), conflict markers can be found in the corresponding files as
+well.
+
+Once the conflict is fixed, the 'resolved' command has to be run to
+clear the conflict state. This command also removes the original files
+involved in the merge for a given file.
+
+Merging two patches into one
+----------------------------
+
+There is no command to do this directly at the moment but one can
+export the patch to be merged and use the 'stg fold' command on the
+generated diff file. Assuming that the merged patch was not already
+applied, the operation will succeed. Pushing the merged patch onto the
+stack will result in an empty patch (StGIT notifying the user) that
+can be safely deleted.
+
+
+.git/ Directory Structure
+=========================
+
+HEAD -> refs/heads/<something>
+objects/
+ ??/
+ ...
refs/
heads/
master - the master commit id
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
+ description - the patch description
+ authname - author's name
+ authemail - author's e-mail
+ commname - committer's name
+ commemail - committer's e-mail
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:
~mdw / stgit / commitdiff