Documentation/guilt.txt

   1 guilt(7)
   2 ========
   3
   4 NAME
   5 ----
   6 guilt - quilt on top of git
   7
   8 SYNOPSIS
   9 --------
  10 'guilt' COMMAND [ARGS]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 Andrew Morton originally developed a set of scripts for maintaining kernel
  16 patches outside of any SCM tool. Others extended these into a suite called
  17 quilt. The basic idea behind quilt is to maintain patches instead of
  18 maintaining source files. Patches can be added, removed or reordered, and
  19 they can be refreshed as you fix bugs or update to a new base revision.
  20 quilt is very powerful, but it is not integrated with the underlying SCM
  21 tools. This makes it difficult to visualize your changes.
  22
  23 Guilt allows one to use quilt functionality on top of a Git repository.
  24 Changes are maintained as patches which are committed into Git.  Commits can
  25 be removed or reordered, and the underlying patch can be refreshed based on
  26 changes made in the working directory. The patch directory can also be
  27 placed under revision control, so you can have a separate history of changes
  28 made to your patches.
  29
  30 PATCHES DIRECTORY
  31 -----------------
  32
  33 In Guilt, all the patches are stored in .git/patches/$branch/, where $branch
  34 is the name of the branch being worked on. This means that one can have a
  35 independent series of patches for each branch present in the repository.
  36 Each of these per-branch directories contains 2 special files:
  37
  38 series: This file contains a list of all the patch filenames relative to the
  39 per-branch patch directory. Empty and commented out lines are ignored.
  40
  41 status: This file contains the state of the stack. What patches are applied.
  42
  43 HOOKS
  44 -----
  45 Any guilt operation may execute zero or more hook scripts which can be used
  46 to run any housekeeping commands or even abort the execution of the command.
  47
  48 include::hooks.txt[]
  49
  50 AUTOTAGGING
  51 -----------
  52
  53 Autotagging is a feature that automatically creates unannotated tags for
  54 top, bottom, and base of the stack.
  55
  56 On every push or pop operation (refresh is a pop followed by a push), Guilt
  57 updates the stack top (${branch}_top), stack bottom (${branch}_bottom), and
  58 stack base (${branch}_base) tags.
  59
  60 Top:: Top-most applied patch/commit
  61 Bottom:: Bottom-most applied patch/commit
  62 Base:: Commit on top of which the bottom most patch is applied
  63
  64 Having these three tags, one can easily get the log/diff/other information
  65 only for commits that are (or are not!) part of the patch stack.
  66
  67 Since some users may not want to have Guilt autotag, a Git config setting
  68 guilt.autotag can be used to turn it on or off.
  69
  70  - If none of the config files (system, global, etc.) contain a guilt.autotag,
  71    the feature defaults to being on.
  72
  73  - If one or more config file contains the value, regular git-config(1) rules
  74    apply.
  75
  76 During linkguilt:guilt-init[1], the rules are:
  77
  78  - If none of the config files contain guilt.autotag, the repository config
  79    file's guilt.autotag is set to the default (on).
  80
  81  - If there already exists a setting in any of the config files, and neither
  82    of the autotagging related options is used, no local value is set.
  83
  84  - If there already exists a setting in any of the config files, but an
  85    autotagging option is specified, the repository config file's guilt.autotag
  86    is set to the value specified on the command line.
  87
  88 GUILT COMMANDS
  89 --------------
  90 All commands can be called with or without a dash. e.g. 'guilt add' or
  91 'guilt-add'
  92
  93 include::cmds.txt[]
  94
  95 Author
  96 ------
  97 Written by Josef "Jeff" Sipek <jeffpc@josefsipek.net>
  98
  99 Documentation
 100 --------------
 101 Documentation by Brandon Philips <brandon@ifup.org> and Josef "Jeff" Sipek
 102 <jeffpc@josefsipek.net>
 103
 104 include::footer.txt[]