Add support for branch description files

[stgit] / doc / tutorial.txt

			    StGIT Tutorial


Introduction
============

StGIT is a Python application providing similar functionality to Quilt
(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 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
================

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:

  stg <cmd> (-h | --help)

Repository initialisation/updating
----------------------------------

To clone a repository (all the GIT repository types are accepted):

  stg clone <repository> <local-dir>

To initialise an existing GIT repository to be used with StGIT (not
needed if the cloning was done using StGIT):

  stg init

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 pull the latest changes from the remote repository (defaulting to
the value in .git/branches/origin):

  stg pull [<branch> or 'origin']

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).

Stack manipulation
------------------

To create/delete a patch:

  stg new <name>
  stg delete <name>

The 'new' command also sets the topmost patch to the newly created
one.

To automatically delete the empty patches:

  stg clean

To push/pop a patch to/from the stack:

  stg push [--all | <name or first unapplied>]
  stg pop [--all | <name or topmost>]

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 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 (or a range of patches):

  stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>]

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:

  stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)

Changes to the topmost patch
----------------------------

Any modified file already under revision control will automatically be
included in the topmost patch.

To add/delete files to/from the topmost patch:

  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

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
    ...
  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/
        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/
        ...
      ...
    ...


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.