Documentation/HOWTO.md

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