summaryrefslogtreecommitdiff
path: root/dgit-maint-gbp.7.pod
blob: 60fab5c9e619d84052fe87658ab0316a0138c667 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
=head1 NAME

dgit - tutorial for package maintainers already using git-buildpackage(1)

=head1 INTRODUCTION

This document explains how B<dgit> can be incorporated into a
git-buildpackage(1) package-maintenance workflow.  This should be read
jointly with git-buildpackage(1)'s documentation.  Some reasons why
you might want to incorporate B<dgit> into your existing workflow:

=over 4

=item

Benefit from dgit's safety catches.  In particular, ensure that your
upload always matches exactly your git HEAD.

=item

Provide a better, more detailed git history to downstream dgit users,
such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
dgit-user(7)).

=item

Incorporate NMUs with a single command (see below).

=back

Note that we assume a patches-unapplied repository: the upstream
source committed to the git repository is unpatched.
git-buildpackage(1) can work with patched-applied repositories, but is
normally used with patches-unapplied.

=head1 GIT CONFIGURATION

If you run

=over 4

    % git config dgit.default.quilt-mode gbp

=back

in your repository, you can omit I<--gbp> wherever it occurs below.

Note that this does require that you always work from your gbp master
branch, never the dgit patches-applied branch.

=head1 BUILDING

If you use gbp-buildpackage(1) to generate your orig tarballs, you
will need to perform the first build with gbp-buildpackage(1) directly
(this is due to Debian bug #841084).

Otherwise, you can perform builds like this:

=over 4

    % dgit [--allow-dirty] gbp-build [OPTIONS]

=back

where I<--allow-dirty> is needed for testing uncommitted changes, and
I<OPTIONS> are any further options to be passed on to
gbp-buildpackage(1).

When you are ready to build for upload, you will probably want to use
sbuild(1) or pbuilder(1), or do a source-only upload.  Either

=over 4

    % dgit --rm-old-changes --gbp sbuild

=back

or

=over 4

    % dgit --rm-old-changes gbp-build --git-pbuilder

=back

or

=over 4

    % dgit --rm-old-changes --gbp build-source

=back

We use I<--rm-old-changes> to ensure that there is exactly one changes
file corresponding to this package, so we can be confident we're
uploading what we intend (though B<dgit push> will do some safety
checks).

Note that all of the commands in this section are not required to
upload with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1) and
sbuild(1) directly.  However, the defaults for these tools may leave
you with something that dgit will refuse to upload because it doesn't
match your git HEAD.  As a general rule, leave all signing and tagging
to dgit.

=head1 UPLOADING

Don't use I<--git-tag>: B<dgit push> will do this for you.  To upload:

=over 4

    % dgit --gbp push

=back

This will push your git history to the dgit-repos, but you probably
want to follow it up with a push to alioth.

You will need to pass I<--overwrite> if the previous upload was not
performed with dgit.

=head1 INCORPORATING NMUS

B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
branches.  You can just apply the NMU diff the traditional way.  The
next upload will require I<--overwrite>.

=head1 SEE ALSO

dgit(1), dgit(7)

=head1 AUTHOR

This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.