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 This section is mostly for those savvy enough to just dive in, and not read
  41 documentation ;) A more detailed description of what is going on is below.
  42
  43 $ cd some_git_repo
  44
  45 # initialize the patch directory
  46 $ guilt-init
  47
  48 # create a new patch called 'patch1'
  49 $ guilt-new patch1
  50
  51 # edit somefile
  52 $ vim somefile
  53
  54 # refresh patch1 with the changes we just made
  55 $ guilt-refresh
  56
  57 # If we look at .git/patches/$branch/patch1, we see a diff with the changes
  58 # we just made
  59
  60 # create a new patch called 'patch2'
  61 $ guilt-new patch2
  62
  63 # edit somefile again
  64 $ vim somefile
  65
  66 # refresh patch2
  67 $ guilt-refresh
  68
  69 # list all applied patches
  70 $ guilt-applied
  71
  72 # list all applied and unapplied patches
  73 $ guilt-series
  74
  75 # pop the top most applied patch
  76 $ guilt-pop
  77
  78 # push the next patch on top of the currently applied patches
  79 $ guilt-push
  80
  81 # pop all patches
  82 $ guilt-pop -a
  83
  84 # push all patches
  85 $ guilt-push -a
  86
  87
  88 Why use Guilt?
  89 ==============
  90
  91 The quilt pdf [3] paper seems to be a good starting point for why use a
  92 quilt-like system. As to why use Guilt over other quilt-like git porceilans,
  93 that's mostly up to:
  94
  95 1) User's taste
  96 2) Format of the patches directory
  97
  98
  99 Working with Guilt:
 100 ===================
 101
 102 First, get a repository to work on. Here's one that we'll use as an example:
 103 $ git-clone git://git.kernel.org/pub/scm/linux/kernel/jsipek/guilt-hello.git
 104
 105 Now, it is time to initialize the patches directory using guilt's init
 106 command:
 107 $ cd hello
 108 $ guilt-init
 109
 110 Create a new patch called "new_hello_string"
 111 $ guilt-new new_hello_string
 112
 113 This creates a new empty file .git/patches/master/new_hello_string.
 114
 115 Now, it is time to change hello.c. Suppose we change the string being
 116 outputed to "Howdy!\n".
 117
 118 Currently, the changes live in the working copy only. Running refresh
 119 refreshes the (currently empty) patch:
 120 $ guilt-refresh
 121
 122 If we look at the patch file again, we'll see that it now contains a patch
 123 that changes the hello string.
 124
 125 Let's create a second patch called "say_name"
 126 $ guilt-new say_name
 127
 128 ...and edit hello.c to output the programs name by adding:
 129
 130 printf("My name is '%s'\n", argv[0]);
 131
 132 And of course, we refresh the patch:
 133 $ guilt-refresh
 134
 135 As you might have expected, this updates the second patch file with the
 136 appropriate diff.
 137
 138
 139 [1] http://www.selenic.com/mercurial/wiki/index.cgi/MqExtension
 140 [2] http://savannah.nongnu.org/projects/quilt
 141 [3] http://www.suse.de/~agruen/quilt.pdf