Guilt v0.37-rc1
[guilt.git] / Documentation / HOWTO.md
blobee07d7fa441c8661e6ce520740ee0cd80b7c40f8
1 Since guilt is heavily based on Mercurial queues (mq), some of the following
2 is shamelessly stolen from the mq page [[1]].
4 Introduction
5 ============
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.
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.
23 Patches Directory
24 =================
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:
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.
34 status: This file contains the state of the stack. What patches are applied.
37 Diving in
38 =========
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.
43         $ cd some_git_repo
45 initialize the patch directory
47         $ guilt init
49 create a new patch called 'patch1'
51         $ guilt new patch1
53 edit somefile
55         $ vim somefile
57 refresh patch1 with the changes we just made
59         $ guilt refresh
61 If we look at .git/patches/$branch/patch1, we see a diff with the changes
62 we just made.
64 Create a new patch called 'patch2'
66         $ guilt new patch2
69 edit somefile again
71         $ vim somefile
73 refresh patch2
75         $ guilt refresh
77 list all applied patches
79         $ guilt applied
81 list all applied and unapplied patches
83         $ guilt series
85 pop the top most applied patch
87         $ guilt pop
89 push the next patch on top of the currently applied patches
91         $ guilt push
93 pop all patches
95         $ guilt pop -a
97 push all patches
99         $ guilt push -a
101 Why use Guilt?
102 ==============
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:
108 1. User's taste
109 2. Format of the patches directory
112 Working with Guilt:
113 ===================
115 First, get a repository to work on. Here's one that we'll use as an example:
117     $ git-clone git://git.kernel.org/pub/scm/linux/kernel/jsipek/guilt-hello.git
119 Now, it is time to initialize the patches directory using guilt's init
120 command:
122     $ cd hello
123     $ guilt init
125 Create a new patch called "new_hello_string"
127     $ guilt new new_hello_string
129 This creates a new empty file `.git/patches/master/new_hello_string`.
131 Now, it is time to change hello.c. Suppose we change the string being
132 outputed to `"Howdy!\n"`.
134 Currently, the changes live in the working copy only. Running refresh
135 refreshes the (currently empty) patch:
137     $ guilt refresh
139 If we look at the patch file again, we'll see that it now contains a patch
140 that changes the hello string.
142 Let's create a second patch called "say_name"
144     $ guilt new say_name
146 ...and edit hello.c to output the programs name by adding:
148     printf("My name is '%s'\n", argv[0]);
150 And of course, we refresh the patch:
152     $ guilt refresh
154 As you might have expected, this updates the second patch file with the
155 appropriate diff.
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