chiark / gitweb /
test suite: Break out t-dgit-manpage
[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 The --overwrite option tells dgit that you are expecting
69 that your git history is not a descendant of the
70 history which dgit synthesised from the previous
71 non-dgit uploads.
72
73 dgit will make a merge commit
74 on your branch
75 but without making any code changes
76 (ie, a pseudo-merge)
77 so that your history,
78 which will be pushed to the dgit git server,
79 is fast forward from the dgit archive view.
80
81 =head1 SUBSEQUENT PUSHES
82
83 =over 4
84
85     % dgit -wgf push
86
87 =back
88
89 That's it.
90
91 =head1 INCORPORATING AN NMU
92
93 =over 4
94
95     % dgit pull
96
97 =back
98
99 That's it.
100
101 Or, if you would prefer to review the changes,
102 you can do this:
103
104 =over 4
105
106     % dgit fetch
107     % dgit diff HEAD..dgit/dgit/sid
108
109 =back
110
111 If you do not merge the NMU into your own git history,
112 the next push will then require I<--overwrite>.
113
114 =head1 SEE ALSO
115
116 dgit(1), dgit(7)