dgit-maint-native.7.pod 2.36 KB
Newer Older
1 2 3 4 5 6
=head1 NAME

dgit - tutorial for package maintainers of Debian-native packages

=head1 INTRODUCTION

7 8 9
This document describes elements of a workflow for using B<dgit> to
maintain a Debian package that uses one of the native source formats
("1.0" & "3.0 (native)").
10 11 12 13 14 15 16 17 18

=over 4

=item

We expect that your git history is fast-forwarding.

=item

19
You should be prepared to tolerate a small amount of
20 21 22 23 24
ugliness in your git history
in the form of merges which stitch
the dgit-generated archive view
into your maintainer history.

25 26 27 28
This is to handle uploads that were not made with dgit,
such as the uploads you made before switching to this workflow,
or NMUs.

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

=head2 Benefits

=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 history
to downstream dgit users.

=item

Incorporate an NMU with one command.

=back

=head1 FIRST PUSH WITH DGIT

You do not need to do anything special to your tree
to push with dgit.

Simply prepare your git tree in the usual way, and then:

=over 4

    % dgit -wgf sbuild -A -c sid
    % dgit -wgf --overwrite push

=back

(Do not make any tags yourself: dgit push will do that.)

68 69 70 71
You may use B<dgit pbuilder> or B<dgit cowbuilder>
instead of B<dgit sbuild>;
see dgit(1) for the syntax of those subcommands.

72 73 74 75 76 77 78 79 80 81 82 83 84
The --overwrite option tells dgit that you are expecting
that your git history is not a descendant of the
history which dgit synthesised from the previous
non-dgit uploads.

dgit will make a merge commit
on your branch
but without making any code changes
(ie, a pseudo-merge)
so that your history,
which will be pushed to the dgit git server,
is fast forward from the dgit archive view.

85 86 87
Alternatively,
if this was the first ever dgit push of the package,
you can avoid this merge commit by
88
passing C<--deliberately-not-fast-forward>
89 90 91 92
instead of C<--overwrite>.
This avoids introducing a new origin commit into
your git history.

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
=head1 SUBSEQUENT PUSHES

=over 4

    % dgit -wgf push

=back

That's it.

=head1 INCORPORATING AN NMU

=over 4

    % dgit pull

=back

That's it.

Or, if you would prefer to review the changes,
you can do this:

=over 4

    % dgit fetch
    % dgit diff HEAD..dgit/dgit/sid

=back

If you do not merge the NMU into your own git history,
the next push will then require I<--overwrite>.

=head1 SEE ALSO

dgit(1), dgit(7)