summaryrefslogtreecommitdiff
path: root/dgit-maint-gbp.7.pod
blob: b8abd66cb6dcce1713ddc6dcb9b15114f412339b (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
135
136
137
138
139
140
141
142
=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)).

=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 have configured an I<export-dir> in your gbp.conf, you should
tell dgit about it:

=over 4

    % git config --global dgit.default.build-products-dir /home/spwhitton/build-area

=back

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

You can perform test builds like this:

=over 4

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

=back

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

If you are doing a source-only upload, you do not need to prepare a
I<_source.changes>, as B<dgit push-source> will take of that on your
behalf.

If you need to include binaries with your upload, you will probably
want to use sbuild(1), pbuilder(1) or cowbuilder(1):

=over 4

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

=back

replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.

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 none of the commands in this section are required to upload
with dgit.  You can invoke gbp-buildpackage(1), pbuilder(1),
cowbuilder(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 do a
source-only upload:

=over 4

    % dgit --gbp push-source

=back

or if you need to include binaries,

=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 salsa.

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

If this is first ever dgit push of the package, consider passing
I<--deliberately-not-fast-forward> instead of I<--overwrite>.  This
avoids introducing a new origin commit into the dgit view of your git
history.  (This origin commit would represent the most recent non-dgit
upload of the package, but this should already be represented in your
git history.)

=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>.