chiark / gitweb /
git-debrebase: convert-from-*: Snag on unused patches
[dgit.git] / dgit-maint-native.7.pod
1 =head1 NAME
2
3 dgit - tutorial for package maintainers of Debian-native packages
4
5 =head1 INTRODUCTION
6
7 This document describes elements of a workflow for using B<dgit> to
8 maintain a Debian package that uses one of the native source formats
9 ("1.0" & "3.0 (native)").
10
11 =over 4
12
13 =item
14
15 We expect that your git history is fast-forwarding.
16
17 =item
18
19 You should be prepared to tolerate a small amount of
20 ugliness in your git history
21 in the form of merges which stitch
22 the dgit-generated archive view
23 into your maintainer history.
24
25 This is to handle uploads that were not made with dgit,
26 such as the uploads you made before switching to this workflow,
27 or NMUs.
28
29 =back
30
31 =head2 Benefits
32
33 =over 4
34
35 =item
36
37 Benefit from dgit's safety catches.  In particular, ensure that your
38 upload always matches exactly your git HEAD.
39
40 =item
41
42 Provide a better,
43 more detailed history
44 to downstream dgit users.
45
46 =item
47
48 Incorporate an NMU with one command.
49
50 =back
51
52 =head1 FIRST PUSH WITH DGIT
53
54 You do not need to do anything special to your tree
55 to push with dgit.
56
57 Simply prepare your git tree in the usual way, and then:
58
59 =over 4
60
61     % dgit -wgf sbuild -A -c sid
62     % dgit -wgf --overwrite push
63
64 =back
65
66 (Do not make any tags yourself: dgit push will do that.)
67
68 You may use B<dgit pbuilder> or B<dgit cowbuilder>
69 instead of B<dgit sbuild>;
70 see dgit(1) for the syntax of those subcommands.
71
72 The --overwrite option tells dgit that you are expecting
73 that your git history is not a descendant of the
74 history which dgit synthesised from the previous
75 non-dgit uploads.
76
77 dgit will make a merge commit
78 on your branch
79 but without making any code changes
80 (ie, a pseudo-merge)
81 so that your history,
82 which will be pushed to the dgit git server,
83 is fast forward from the dgit archive view.
84
85 Alternatively,
86 if this was the first ever dgit push of the package,
87 you can avoid this merge commit by
88 passing C<--deliberately-not-fast-forward>.
89 instead of C<--overwrite>.
90 This avoids introducing a new origin commit into
91 your git history.
92
93 =head1 SUBSEQUENT PUSHES
94
95 =over 4
96
97     % dgit -wgf push
98
99 =back
100
101 That's it.
102
103 =head1 INCORPORATING AN NMU
104
105 =over 4
106
107     % dgit pull
108
109 =back
110
111 That's it.
112
113 Or, if you would prefer to review the changes,
114 you can do this:
115
116 =over 4
117
118     % dgit fetch
119     % dgit diff HEAD..dgit/dgit/sid
120
121 =back
122
123 If you do not merge the NMU into your own git history,
124 the next push will then require I<--overwrite>.
125
126 =head1 SEE ALSO
127
128 dgit(1), dgit(7)