dgit-user.7.pod

   1 =head1 NAME
   2
   3 dgit - tutorial for users of Debian-derived distros supported by dgit
   4
   5 =head1 INTRODUCTION
   6
   7 dgit lets you fetch the source code to every package on your
   8 system
   9  as if your distro used git to maintain all of it.
  10
  11 You can then edit it,
  12 build updated binary packages
  13 and install and run them.
  14 You can also share your work with others.
  15
  16 This tutorial assumes you have basic familiarity with git.
  17 It does not assume any initial familiarity with
  18  Debian's packaging processes.
  19
  20 =head1 SUMMARY
  21
  22 =over 4
  23
  24     % dgit clone glibc jessie
  25     % cd glibc
  26     % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
  27     % git commit -a -m 'Fix libc lost output bug'
  28     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
  29     % sudo apt-get build-dep glibc
  30     % dpkg-buildpackage -uc -b
  31     % sudo dpkg -i ../libc6_*.deb
  32
  33 =back
  34
  35 Later:
  36
  37 =over 4
  38
  39     % cd glibc
  40     % dgit pull jessie
  41     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
  42     % dpkg-buildpackage -uc -b
  43     % sudo dpkg -i ../libc6_*.deb
  44
  45 =back
  46
  47 =head1 FINDING THE RIGHT SOURCE CODE - DGIT CLONE
  48
  49 dgit clone needs to be told the source package name
  50 (which might be different to the binary package name)
  51 and the codename of the Debian release
  52 (this is called the "suite").
  53
  54 =head2 Finding the source package name
  55
  56 For many packages, the source package name is obvious.
  57 Otherwise, if you know a file that's in the package,
  58 you can look it up with dpkg:
  59
  60 =over 4
  61
  62     % dpkg -S /lib/i386-linux-gnu/libc.so.6
  63     libc6:i386: /lib/i386-linux-gnu/libc.so.6
  64     % dpkg -s libc6:i386
  65     Package: libc6
  66     Status: install ok installed
  67     ...
  68     Source: glibc
  69
  70 =back
  71
  72 (In this example,
  73 libc6 is a "multi-arch: allowed" package,
  74  which means that it exists in several different builds
  75  for different architectures.
  76 That's where C<:i386> comes from.)
  77
  78 =head2 Finding the Debian release (the "suite")
  79
  80 Internally,
  81 Debian (and derived) distros normally refer to their releases by codenames.
  82 So for example, at the time of writing
  83 Debian C<jessie> (Debian 8) is Debian stable and
  84 the current version of Ubuntu is C<yakkety> (Yakkety Yak, 16.10).
  85
  86 If you don't know what you're running, try this:
  87
  88 =over 4
  89
  90     % grep '^deb' /etc/apt/sources.list
  91     deb http://the.earth.li/debian/ jessie main non-free contrib
  92     ...
  93     %
  94
  95 =back
  96
  97 =head1 EDITING THE SOURCE CODE
  98
  99 =head2 What kind of source tree you get when you dgit clone
 100
 101 If the Debian package is actually a version of an upstream release,
 102 the code layout should be like the upstream version.
 103 You should find that git commands C<git grep> work properly.
 104
 105 The package's Debian metadata and the script for building binary
 106 packages are under C<debian/>.
 107 C<debian/control>, C<debian/changelog> and C<debian/rules> are the
 108 starting points.
 109 The Debian Policy Manual has most of the in-depth
 110 technical details.
 111
 112 For many Debian packages,
 113 there will also be some things in C<debian/patches/>.
 114 These will probably be in your git history
 115 (one way or another),
 116 and they are not used when building a package
 117 based on a git histroy obtained with dgit.
 118 It is best to ignore them.
 119
 120 =head2 What kind of history you get
 121
 122 If you're lucky, the history will be a version of,
 123 or based on,
 124 the Debian maintainer's own git history,
 125 or upstream's git history.
 126
 127 But for many packages the real git history
 128 does not exist or
 129 cannot be obtained in a standard form
 130 So yuu may find that the history is a rather short
 131 history invented by dgit.
 132
 133 dgit histories often contain automatically-generated commits,
 134 including commits which make no changes but just serve
 135 to make a rebasing branch fast-forward.
 136
 137 If the package maintainer is using git then
 138 after dgit clone
 139 you may find that there is a useful C<vcs-git> remote
 140 referring to the Debian package maintainers repository
 141 for the pacakge.
 142 You can see what's there with C<git fetch vcs-git>.
 143 But use what you find there with care:
 144 Debian maintainers' git histories are often in
 145 formats which are very confusing and idiosyncratic
 146 from the point of view of those new to Debian git packaging.
 147
 148 =head1 BUILDING
 149
 150 =head2 Always commit first
 151
 152 When using git with some arbitrary Debian package
 153 you should normally commit before building.
 154
 155 This is because Debian package builds are often quite messy:
 156 they may modify files which are also committed to git,
 157 or leave outputs and teporary files not covered by C<.gitignore>.
 158 Kf you always commit,
 159 you can use C<git reset --hard> and C<git clean -xdf>
 160 to put things back.
 161 But if you create a new file
 162 B<don't forget> to say C<git add>, and commit,
 163 as otherwise C<git clean> will delete your new file.
 164
 165 =head2 Update the changelog (at least once)
 166
 167 The binaries you build will have a version number which ultimately
 168 comes from the C<debian/changelog>.  You want to be able to tell your
 169 binaries apart from your distro's.
 170
 171 So you should update C<debian/changelog>
 172 to add a new stanza at the top,
 173 for your build.
 174 An easy way to do this is this rune:
 175
 176 =over 4
 177
 178     % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
 179
 180 =back
 181
 182 which adds a new entry with a new version number chosen in a
 183 reasonably sensible way, and commits the result to your git branch.
 184
 185 =head1 INSTALLING
 186
 187 You can use C<dpkg -i> to install the
 188 .debs that came out of your package.
 189
 190 If the dependencies aren't installed,
 191 you will get an error, which can usually be fixed with
 192 C<apt-get -f install>.
 193
 194 =head1 SHARING YOUR WORK
 195
 196 The C<dgit/jessie> branch (or whatever) is a normal git branch.
 197 You can use C<git push> to any suitable git server.
 198
 199 If you want to contribute your changes back to Debian,
 200 you should probably send them as attachments to
 201 an email to the
 202 L<Debian Bug System|https://bugs.debian.org/>
 203 (either a followup to an existing bug, or a new bug).
 204 Patches in C<<git-format-patch> format are usually very welcome.
 205
 206 Anyone who gets that git branch from you
 207 will be able to build binary packages
 208 just as you did.
 209
 210 However, the
 211 git branch is not sufficient to build a I<source package>.
 212 Source packages are somewhat awkward to work with.
 213 Indeed many plausible git histories or git trees
 214 cannot be converted into a suitable source package.
 215 So I recommend you share your git branch instead.
 216 If you need to provide a source package,
 217 you will probably want to read one of the other tutorials,
 218 such as L<dgit-nmu-simple(7)>, L<dgit-sponsorship(7)> or
 219  L<dgit-maint-*(7)>
 220
 221 multi-arch clash problem
 222
 223
 224 xxx
 225
 226 =head1 SEE ALSO
 227
 228 dgit(1), dgit(7)
 229
 230 =head1 AUTHOR
 231
 232 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.  It contains contributions from other dgit contributors too - see the dgit copyright file.