chiark / gitweb /
dgit: aptget: un-disable cache clean
[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 maintaining a
8 native Debian package using B<dgit>.
9
10 =over 4
11
12 =item
13
14 We expect that your git history is fast-forwarding.
15
16 =item
17
18 You should be prepared to tolerate a small amount of
19 ugliness in your git history
20 in the form of merges which stitch
21 the dgit-generated archive view
22 into your maintainer history.
23
24 This is to handle uploads that were not made with dgit,
25 such as the uploads you made before switching to this workflow,
26 or NMUs.
27
28 =back
29
30 =head2 Benefits
31
32 =over 4
33
34 =item
35
36 Benefit from dgit's safety catches.  In particular, ensure that your
37 upload always matches exactly your git HEAD.
38
39 =item
40
41 Provide a better,
42 more detailed history
43 to downstream dgit users.
44
45 =item
46
47 Incorporate an NMU with one command.
48
49 =back
50
51 =head1 FIRST PUSH WITH DGIT
52
53 You do not need to do anything special to your tree
54 to push with dgit.
55
56 Simply prepare your git tree in the usual way, and then:
57
58 =over 4
59
60     % dgit -wgf sbuild -A -c sid
61     % dgit -wgf --overwrite push
62
63 =back
64
65 (Do not make any tags yourself: dgit push will do that.)
66
67 The --overwrite option tells dgit that you are expecting
68 that your git history is not a descendant of the
69 history which dgit synthesised from the previous
70 non-dgit uploads.
71
72 dgit will make a merge commit
73 on your branch
74 but without making any code changes
75 (ie, a pseudo-merge)
76 so that your history,
77 which will be pushed to the dgit git server,
78 is fast forward from the dgit archive view.
79
80 =head1 SUBSEQUENT PUSHES
81
82 =over 4
83
84     % dgit -wgf push
85
86 =back
87
88 That's it.
89
90 =head1 INCORPORATING AN NMU
91
92 =over 4
93
94     % dgit pull
95
96 =back
97
98 That's it.
99
100 Or, if you would prefer to review the changes,
101 you can do this:
102
103 =over 4
104
105     % dgit fetch
106     % dgit diff HEAD..dgit/dgit/sid
107
108 =back
109
110 If you do not merge the NMU into your own git history,
111 the next push will then require I<--overwrite>.
112
113 =head1 SEE ALSO
114
115 dgit(1), dgit(7)