Documentation/HOWTO

   1 Since guilt is heavily based on Mercurial queues (mq), some of the following
   2 is shamelessly stolen from the mq page [1].
   3
   4 Introduction:
   5 =============
   6
   7 Andrew Morton originally developed a set of scripts for maintaining kernel
   8 patches outside of any SCM tool. Others extended these into a suite called
   9 quilt [2]. The basic idea behind quilt is to maintain patches instead of
  10 maintaining source files. Patches can be added, removed or reordered, and
  11 they can be refreshed as you fix bugs or update to a new base revision.
  12 quilt is very powerful, but it is not integrated with the underlying SCM
  13 tools. This makes it difficult to visualize your changes.
  14
  15 Guilt allows one to use quilt functionality on top of a Git repository.
  16 Changes are maintained as patches which are committed into Git.  Commits can
  17 be removed or reordered, and the underlying patch can be refreshed based on
  18 changes made in the working directory. The patch directory can also be
  19 placed under revision control, so you can have a separate history of changes
  20 made to your patches.
  21
  22
  23 Patches Directory:
  24 ==================
  25
  26 In Guilt, all the patches are stored in .git/patches/$branch/, where $branch
  27 is the name of the branch being worked on. This means that one can have a
  28 independent series of patches for each branch present in the repository.
  29 Each of these per-branch directories contains 2 special files:
  30
  31 series: This file contains a list of all the patch filenames relative to the
  32 per-branch patch directory. Empty and commented out lines are ignored.
  33
  34 status: This file contains the state of the stack. What patches are applied.
  35
  36
  37 Diving in:
  38 ==========
  39
  40 $ cd some_git_repo
  41
  42 # initialize the patch directory
  43 $ guilt-init
  44
  45 # create a new patch called 'patch1'
  46 $ guilt-new patch1
  47
  48 # edit somefile
  49 $ vim somefile
  50
  51 # refresh patch1 with the changes we just made
  52 $ guilt-refresh
  53
  54 # If we look at .git/patches/$branch/patch1, we see a diff with the changes
  55 # we just made
  56
  57 # create a new patch called 'patch2'
  58 $ guilt-new patch2
  59
  60 # edit somefile again
  61 $ vim somefile
  62
  63 # refresh patch2
  64 $ guilt-refresh
  65
  66 # list all applied patches
  67 $ guilt-applied
  68
  69 # list all applied and unapplied patches
  70 $ guilt-series
  71
  72 # pop the top most applied patch
  73 $ guilt-pop
  74
  75 # push the next patch on top of the currently applied patches
  76 $ guilt-push
  77
  78 # pop all patches
  79 $ guilt-pop -a
  80
  81 # push all patches
  82 $ guilt-push -a
  83
  84
  85 [1] http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension
  86 [2] http://savannah.nongnu.org/projects/quilt