chiark / gitweb /
git-debrebase: document that breakwater merges always have single parent
[dgit.git] / dgit-maint-gbp.7.pod
1 =head1 NAME
2
3 dgit - tutorial for package maintainers already using git-buildpackage(1)
4
5 =head1 INTRODUCTION
6
7 This document explains how B<dgit> can be incorporated into a
8 git-buildpackage(1) package-maintenance workflow.  This should be read
9 jointly with git-buildpackage(1)'s documentation.  Some reasons why
10 you might want to incorporate B<dgit> into your existing workflow:
11
12 =over 4
13
14 =item
15
16 Benefit from dgit's safety catches.  In particular, ensure that your
17 upload always matches exactly your git HEAD.
18
19 =item
20
21 Provide a better, more detailed git history to downstream dgit users,
22 such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
23 dgit-user(7)).
24
25 =back
26
27 Note that we assume a patches-unapplied repository: the upstream
28 source committed to the git repository is unpatched.
29 git-buildpackage(1) can work with patched-applied repositories, but is
30 normally used with patches-unapplied.
31
32 =head1 GIT CONFIGURATION
33
34 If you run
35
36 =over 4
37
38     % git config dgit.default.quilt-mode gbp
39
40 =back
41
42 in your repository, you can omit I<--gbp> wherever it occurs below.
43
44 Note that this does require that you always work from your gbp master
45 branch, never the dgit patches-applied branch.
46
47 =head1 BUILDING
48
49 You can perform builds like this:
50
51 =over 4
52
53     % dgit [--allow-dirty] gbp-build [OPTIONS]
54
55 =back
56
57 where I<--allow-dirty> is needed for testing uncommitted changes, and
58 I<OPTIONS> are any further options to be passed on to
59 gbp-buildpackage(1).
60
61 When you are ready to build for upload, you will probably want to use
62 sbuild(1) or pbuilder(1), or do a source-only upload.  Either
63
64 =over 4
65
66     % dgit --rm-old-changes --gbp sbuild
67
68 =back
69
70 or
71
72 =over 4
73
74     % dgit --rm-old-changes gbp-build --git-pbuilder
75
76 =back
77
78 or
79
80 =over 4
81
82     % dgit --rm-old-changes --gbp build-source
83
84 =back
85
86 We use I<--rm-old-changes> to ensure that there is exactly one changes
87 file corresponding to this package, so we can be confident we're
88 uploading what we intend (though B<dgit push> will do some safety
89 checks).
90
91 Note that all of the commands in this section are not required to
92 upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
93 sbuild(1) directly.  However, the defaults for these tools may leave
94 you with something that dgit will refuse to upload because it doesn't
95 match your git HEAD.  As a general rule, leave all signing and tagging
96 to dgit.
97
98 =head1 UPLOADING
99
100 Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:
101
102 =over 4
103
104     % dgit --gbp push
105
106 =back
107
108 This will push your git history to the dgit-repos, but you probably
109 want to follow it up with a push to alioth.
110
111 You will need to pass I<--overwrite> if the previous upload was not
112 performed with dgit.
113
114 If this is first ever dgit push of the package, consider passing
115 I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
116 avoids introducing a new origin commit into the dgit view of your git
117 history.  (This origin commit would represent the most recent non-dgit
118 upload of the package, but this should already be represented in your
119 git history.)
120
121 =head1 INCORPORATING NMUS
122
123 B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
124 branches.  You can just apply the NMU diff the traditional way.  The
125 next upload will require I<--overwrite>.
126
127 =head1 SEE ALSO
128
129 dgit(1), dgit(7)
130
131 =head1 AUTHOR
132
133 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.