summaryrefslogtreecommitdiff
path: root/git-debpush.1.pod
blob: 926e8cd3faeedffda81962b120c6ac0d2e2268aa (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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
=head1 NAME

git-debpush - create & push a git tag with metadata for an ftp-master upload

=head1 SYNOPSIS

B<git debpush> [I<option>...]

=head1 DESCRIPTION

B<git-debpush> is a wrapper around git-tag(1) and git-push(1).  It
helps you create and push a specially formatted signed tag which
indicates that the tagged commit should be pushed (or "uploaded") to a
Debian-style archive.

Typically, your git server will be configured to notify an
intermediary service of the new tag that you pushed.  That service
will then fetch your tag, check your PGP signature, do any conversion
that's needed (such as producing and signing a B<.dsc> and
B<.changes>), and upload the result to the Debian-style archive.

B<git-debpush> is only for source-only uploads.

=head1 TYPICAL USAGE

B<git-debpush> is designed such that for regular uploads of your
package, you should be able to just invoke it without passing any
command line arguments.  After you've built and tested some .debs, run
dch(1) to finalise your changelog and committed the result, just type
"git debpush", and the intermediary service and your distribution's
autobuilder network will take care of the rest.

The most common exception to this is the first time you use
B<git-debpush> for a non-native package.  You will need to pass a
quilt mode option to inform the intermediary service which git branch
format you are using, for example

=over 4

    % git debpush --gbp

=back

if you are using the git branch format typically used with gbp(1).
See "QUILT MODE OPTIONS", below, for the available quilt mode options.

Aside from a few sanity checks to help avoid broken uploads,
B<git-debpush> does not do anything with the information provided by
the quilt mode option.  It simply embeds the corresponding quilt mode
in its generated tag, for use by the intermediary service.

Future invocations of B<git-debpush> will try to read the quilt mode
out of the tag generated by B<git-debpush> for your previous upload.
You can override that on the command line by passing a quilt mode
option, which always takes precedence.

=head1 SETUP FOR SOURCE FORMAT 1.0

B<git-debpush> needs to tell the intermediary git service whether this
is a native or non-native package.  Given historical Debian practices,
it is not sufficient for either B<git-debpush> or the intermediary
service to rely on the version number in debian/changelog.

If you are using one of the 3.0 source package formats, B<git-debpush>
will just look in debian/source/format to determine whether the
package is native or non-native, and you can ignore this section of
the manpage.

If you are using the 1.0 source package format -- either
debian/source/format does not exist, or contains the string "1.0" --
then B<git-debpush> must be told whether the package is native or
non-native.  We do this using debian/source/options.  If your package
is non-native, execute

=over 4

    % echo "-sn" >>debian/source/options

=back

If your package is native, execute

=over 4

    % echo "-sk" >>debian/source/options

=back

(With source format 1.0, dpkg-source(1) decides whether the package is
native or non-native based on the presence of absence of an orig.tar
in B<..>, but B<git-debpush> is a pure git tool that never looks at
tarballs.)

=head1 QUILT MODE OPTIONS

=over 4

=item B<--quilt=gbp>|B<--gbp>

You are using the 'unapplied' branch format, typically used with
gbp(1).

=item B<--quilt=dpm>|B<--dpm>

You are using git-dpm(1)'s branch format.

=item B<--quilt=baredebian[+git]>|B<--baredebian[+git]>

You are using the 'bare debian' branch format, with the upstream
source in the form of an upstream tag.

=item B<--quilt=baredebian+tarball>|B<--baredebian+tarball>

You are using the 'bare debian' branch format, with the upstream
source in the form of a tarball.

=item B<--quilt=linear>

You are using the 'manually maintained applied' branch format or
similar, and each commit touching the upstream source not already
represented in debian/patches should be added as a new patch.

=item B<--quilt=smash>

You are using the 'manually maintained applied' branch format or
similar, and you want all changes to the upstream source to be
squashed into a single patch in debian/patches.

=item B<--quilt=auto>

Tell the intermediary service to try B<--quilt=linear>, and if that
cannot succeed, fall back to B<--quilt=smash>.

=item B<--quilt=nofix>

You are using the 'manually maintained applied' branch format or
similar, and you don't want debian/patches to be touched by the
intermediary service.

If all commits touching the upstream source are not already
represented in debian/patches, the intermediary service will fail to
upload your package.

=back

=head1 OTHER OPTIONS

=over 4

=item B<--no-push>|B<-n>

Just tag, don't push.

=item B<--force>|B<-f>

Don't perform checks designed to prevent broken uploads.

=item B<-u> I<keyid>

Passed on to git-tag(1).

=item B<--branch=>I<BRANCH>

Where to place the tag, i.e., what you want to release.  If
unspecified, we put the tag on whatever HEAD points to.

Note that this need not actually be a branch, but any committish (see
gitglossary(7)).  The option name is chosen to fit what is by far the
most common case.

=item B<--remote=>I<REMOTE>

Where to push tags and branches.  If unspecified, use the remote which
git would use if you typed "git push BRANCH".

=item B<--distro=>I<DISTRO>

What distribution name to embed in the signed tag.  Defaults to
"debian".

=back

=head1 SEE ALSO

Git branch formats in use by Debian maintainers:
<https://wiki.debian.org/GitPackagingSurvey>

=head1 AUTHOR

B<git-debpush> was written by Sean Whitton <spwhitton@spwhitton.name>
with much input from Ian Jackson <ijackson@chiark.greenend.org.uk>.