1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2018-10-04 01:04+0100\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: ../dgit.1:3 ../dgit.7:2 ../dgit-user.7.pod:1 ../dgit-nmu-simple.7.pod:1
21 #: ../dgit-maint-native.7.pod:1 ../dgit-maint-merge.7.pod:1
22 #: ../dgit-maint-gbp.7.pod:1 ../dgit-maint-debrebase.7.pod:1
23 #: ../dgit-downstream-dsc.7.pod:1 ../dgit-sponsorship.7.pod:1
24 #: ../git-debrebase.1.pod:1 ../git-debrebase.5.pod:1
30 #: ../dgit.1:1394 ../dgit.7:23 ../dgit-user.7.pod:447
31 #: ../dgit-nmu-simple.7.pod:137 ../dgit-maint-native.7.pod:126
32 #: ../dgit-maint-merge.7.pod:491 ../dgit-maint-gbp.7.pod:136
33 #: ../dgit-maint-debrebase.7.pod:722 ../dgit-downstream-dsc.7.pod:352
34 #: ../dgit-sponsorship.7.pod:321 ../git-debrebase.1.pod:601
35 #: ../git-debrebase.5.pod:678
41 #: ../dgit.7:4 ../dgit-user.7.pod:27 ../dgit-nmu-simple.7.pod:35
47 #: ../dgit-user.7.pod:3
48 msgid "dgit-user - making and sharing changes to Debian packages, with git"
52 #: ../dgit-user.7.pod:5 ../dgit-maint-native.7.pod:5
53 #: ../dgit-maint-merge.7.pod:5 ../dgit-maint-gbp.7.pod:5
54 #: ../dgit-maint-debrebase.7.pod:5 ../dgit-downstream-dsc.7.pod:5
55 #: ../git-debrebase.1.pod:10 ../git-debrebase.5.pod:5
60 #: ../dgit-user.7.pod:7
62 "dgit lets you fetch the source code to every package on your system as if "
63 "your distro used git to maintain all of it."
67 #: ../dgit-user.7.pod:11
69 "You can then edit it, build updated binary packages (.debs) and install and "
70 "run them. You can also share your work with others."
74 #: ../dgit-user.7.pod:16
76 "This tutorial gives some recipes and hints for this. It assumes you have "
77 "basic familiarity with git. It does not assume any initial familiarity with "
78 "Debian's packaging processes."
82 #: ../dgit-user.7.pod:21
84 "If you are a package maintainer within Debian; a DM or DD; and/or a sponsee: "
85 "this tutorial is not for you. Try L<dgit-nmu-simple(7)>, L<dgit-maint-"
86 "*(7)>, or L<dgit(1)> and L<dgit(7)>."
90 #: ../dgit-user.7.pod:29
91 msgid "(These runes will be discussed later.)"
95 #: ../dgit-user.7.pod:33
98 " % dgit clone glibc jessie,-security\n"
100 " % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u\n"
101 " % git commit -a -m 'Fix libc lost output bug'\n"
102 " % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit\n"
103 " % mk-build-deps --root-cmd=sudo --install\n"
104 " % dpkg-buildpackage -uc -b\n"
105 " % sudo dpkg -i ../libc6_*.deb\n"
110 #: ../dgit-user.7.pod:44
111 msgid "Occasionally:"
115 #: ../dgit-user.7.pod:48 ../dgit-user.7.pod:242
118 " % git clean -xdf\n"
119 " % git reset --hard\n"
124 #: ../dgit-user.7.pod:53
129 #: ../dgit-user.7.pod:57
133 " % dgit pull jessie,-security\n"
134 " % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit\n"
135 " % dpkg-buildpackage -uc -b\n"
136 " % sudo dpkg -i ../libc6_*.deb\n"
141 #: ../dgit-user.7.pod:65
142 msgid "FINDING THE RIGHT SOURCE CODE - DGIT CLONE"
146 #: ../dgit-user.7.pod:69
149 " % dgit clone glibc jessie,-security\n"
155 #: ../dgit-user.7.pod:74
157 "dgit clone needs to be told the source package name (which might be "
158 "different to the binary package name, which was the name you passed to \"apt-"
159 "get install\") and the codename or alias of the Debian release (this is "
160 "called the \"suite\")."
164 #: ../dgit-user.7.pod:80
165 msgid "Finding the source package name"
169 #: ../dgit-user.7.pod:82
171 "For many packages, the source package name is obvious. Otherwise, if you "
172 "know a file that's in the package, you can look it up with dpkg:"
176 #: ../dgit-user.7.pod:88
179 " % dpkg -S /lib/i386-linux-gnu/libc.so.6 \n"
180 " libc6:i386: /lib/i386-linux-gnu/libc.so.6\n"
181 " % dpkg -s libc6:i386\n"
183 " Status: install ok installed\n"
190 #: ../dgit-user.7.pod:98
193 "(In this example,\n"
194 "libc6 is a \"multi-arch: allowed\" package,\n"
195 " which means that it exists in several different builds\n"
196 " for different architectures.\n"
197 "That's where C<:i386> comes from.)\n"
202 #: ../dgit-user.7.pod:104
203 msgid "Finding the Debian release (the \"suite\")"
207 #: ../dgit-user.7.pod:106
209 "Internally, Debian (and derived) distros normally refer to their releases by "
210 "codenames. Debian also has aliases which refer to the current stable "
211 "release etc. So for example, at the time of writing Debian C<jessie> "
212 "(Debian 8) is Debian C<stable>; and the current version of Ubuntu is "
213 "C<yakkety> (Yakkety Yak, 16.10). You can specify either the codename "
214 "C<jessie> or the alias C<stable>. If you don't say, you get C<sid>, which "
215 "is Debian C<unstable> - the main work-in progress branch."
219 #: ../dgit-user.7.pod:117
220 msgid "If you don't know what you're running, try this:"
224 #: ../dgit-user.7.pod:121
227 " % grep '^deb' /etc/apt/sources.list\n"
228 " deb http://the.earth.li/debian/ jessie main non-free contrib\n"
235 #: ../dgit-user.7.pod:128
237 "For Debian, you should add C<,-security> to the end of the suite name, "
238 "unless you're on unstable or testing. Hence, in our example C<jessie> "
239 "becomes C<jessie,-security>. (Yes, with a comma.)"
243 #: ../dgit-user.7.pod:135
244 msgid "WHAT DGIT CLONE PRODUCES"
248 #: ../dgit-user.7.pod:137
249 msgid "What branches are there"
253 #: ../dgit-user.7.pod:139
255 "dgit clone will give you a new working tree, and arrange for you to be on a "
256 "branch named like C<dgit/jessie,-security> (yes, with a comma in the branch "
261 #: ../dgit-user.7.pod:143
263 "For each release (like C<jessie>) there is a tracking branch for the "
264 "contents of the archive, called C<remotes/dgit/dgit/jessie> (and similarly "
265 "for other suites). This can be updated with C<dgit fetch jessie>. This, "
266 "the I<remote suite branch>, is synthesized by your local copy of dgit. It "
267 "is fast forwarding."
271 #: ../dgit-user.7.pod:152
273 "Debian separates out the security updates, into C<*-security>. Telling dgit "
274 "C<jessie,-security> means that it should include any updates available in "
275 "C<jessie-security>. The comma notation is a request to dgit to track "
276 "jessie, or jessie-security if there is an update for the package there."
280 #: ../dgit-user.7.pod:158
282 "(You can also dgit fetch in a tree that wasn't made by dgit clone. If "
283 "there's no C<debian/changelog> you'll have to supply a C<-p>I<package> "
284 "option to dgit fetch.)"
288 #: ../dgit-user.7.pod:162
289 msgid "What kind of source tree do you get"
293 #: ../dgit-user.7.pod:164
295 "If the Debian package is based on some upstream release, the code layout "
296 "should be like the upstream version. You should find C<git grep> helpful to "
297 "find where to edit."
301 #: ../dgit-user.7.pod:168
303 "The package's Debian metadata and the scripts for building binary packages "
304 "are under C<debian/>. C<debian/control>, C<debian/changelog> and C<debian/"
305 "rules> are the starting points. The Debian Policy Manual has most of the in-"
306 "depth technical details."
310 #: ../dgit-user.7.pod:175
312 "For many Debian packages, there will also be some things in C<debian/patches/"
313 ">. It is best to ignore these. Insofar as they are relevant the changes "
314 "there will have been applied to the actual files, probably by means of "
315 "actual comments in the git history. The contents of debian/patches are "
316 "ignored when building binaries from dgitish git branches."
320 #: ../dgit-user.7.pod:185
322 "(For Debian afficionados: the git trees that come out of dgit are \"patches-"
323 "applied packaging branches without a .pc directory\".)"
327 #: ../dgit-user.7.pod:190
328 msgid "What kind of history you get"
332 #: ../dgit-user.7.pod:192
334 "If you're lucky, the history will be a version of, or based on, the Debian "
335 "maintainer's own git history, or upstream's git history."
339 #: ../dgit-user.7.pod:197
341 "But for many packages the real git history does not exist, or has not been "
342 "published in a dgitish form. So you may find that the history is a rather "
343 "short history invented by dgit."
347 #: ../dgit-user.7.pod:203
349 "dgit histories often contain automatically-generated commits, including "
350 "commits which make no changes but just serve to make a rebasing branch fast-"
351 "forward. This is particularly true of combining branches like C<jessie,-"
356 #: ../dgit-user.7.pod:210
358 "If the package maintainer is using git then after dgit clone you may find "
359 "that there is a useful C<vcs-git> remote referring to the Debian package "
360 "maintainer's repository for the package. You can see what's there with "
361 "C<git fetch vcs-git>. But use what you find there with care: Debian "
362 "maintainers' git repositories often have contents which are very confusing "
363 "and idiosyncratic. In particular, you may need to manually apply the "
364 "patches that are in debian/patches before you do anything else!"
368 #: ../dgit-user.7.pod:222 ../dgit-maint-gbp.7.pod:56
373 #: ../dgit-user.7.pod:224
374 msgid "Always commit before building"
378 #: ../dgit-user.7.pod:228
381 " % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u\n"
382 " % git commit -a -m 'Fix libc lost output bug'\n"
387 #: ../dgit-user.7.pod:233
389 "Debian package builds are often quite messy: they may modify files which are "
390 "also committed to git, or leave outputs and temporary files not covered by "
395 #: ../dgit-user.7.pod:237
396 msgid "If you always commit, you can use"
400 #: ../dgit-user.7.pod:247
402 "to tidy up after a build. (If you forgot to commit, don't use those "
403 "commands; instead, you may find that you can use C<git add -p> to help "
404 "commit what you actually wanted to keep.)"
408 #: ../dgit-user.7.pod:252
410 "These are destructive commands which delete all new files (so you B<must> "
411 "remember to say C<git add>) and throw away edits to every file (so you "
412 "B<must> remember to commit)."
416 #: ../dgit-user.7.pod:257
417 msgid "Update the changelog (at least once) before building"
421 #: ../dgit-user.7.pod:261
424 " % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit\n"
429 #: ../dgit-user.7.pod:265
431 "The binaries you build will have a version number which ultimately comes "
432 "from the C<debian/changelog>. You want to be able to tell your binaries "
433 "apart from your distro's."
437 #: ../dgit-user.7.pod:270
439 "So you should update C<debian/changelog> to add a new stanza at the top, for "
444 #: ../dgit-user.7.pod:274
446 "This rune provides an easy way to do this. It adds a new changelog entry "
447 "with an uninformative message and a plausible version number (containing a "
448 "bit of your git commit id)."
452 #: ../dgit-user.7.pod:279
454 "If you want to be more sophisticated, the package C<dpkg-dev-el> has a good "
455 "Emacs mode for editing changelogs. Alternatively, you could edit the "
456 "changelog with another text editor, or run C<dch> or C<gbp dch> with "
457 "different options. Choosing a good version number is slightly tricky and a "
458 "complete treatment is beyond the scope of this tutorial."
462 #: ../dgit-user.7.pod:287
463 msgid "Actually building"
467 #: ../dgit-user.7.pod:291
470 " % mk-build-deps --root-cmd=sudo --install\n"
471 " % dpkg-buildpackage -uc -b\n"
476 #: ../dgit-user.7.pod:296
478 "dpkg-buildpackage is the primary tool for building a Debian source package. "
479 "C<-uc> means not to pgp-sign the results. C<-b> means build all binary "
480 "packages, but not to build a source package."
484 #: ../dgit-user.7.pod:302
489 #: ../dgit-user.7.pod:304
491 "You can build in an schroot chroot, with sbuild, instead of in your main "
492 "environment. (sbuild is used by the Debian build daemons.)"
496 #: ../dgit-user.7.pod:309
499 " % git clean -xdf\n"
500 " % sbuild -c jessie -A --no-clean-source \\\n"
501 " --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'\n"
506 #: ../dgit-user.7.pod:315
508 "Note that this will seem to leave a \"source package\" (.dsc and .tar.gz) "
509 "in the parent directory, but that source package should not be used. It is "
510 "likely to be broken. For more information see Debian bug #868527."
514 #: ../dgit-user.7.pod:322
519 #: ../dgit-user.7.pod:324
520 msgid "Debian Jessie or older"
524 #: ../dgit-user.7.pod:328
527 " % sudo dpkg -i ../libc6_*.deb\n"
532 #: ../dgit-user.7.pod:332
534 "You can use C<dpkg -i> to install the .debs that came out of your package."
538 #: ../dgit-user.7.pod:335
540 "If the dependencies aren't installed, you will get an error, which can "
541 "usually be fixed with C<apt-get -f install>."
545 #: ../dgit-user.7.pod:339
546 msgid "Debian Stretch or newer"
550 #: ../dgit-user.7.pod:343
553 " % sudo apt install ../libc6_*.deb\n"
558 #: ../dgit-user.7.pod:347
563 #: ../dgit-user.7.pod:349
565 "If you're working on a library package and your system has multiple "
566 "architectures enabled, you may see something like this:"
570 #: ../dgit-user.7.pod:355
573 " dpkg: error processing package libpcre3-dev:amd64 (--configure):\n"
574 " package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)\n"
579 #: ../dgit-user.7.pod:360
581 "The multiarch system used by Debian requires each package which is present "
582 "for multiple architectures to be exactly the same across all the "
583 "architectures for which it is installed."
587 #: ../dgit-user.7.pod:364
589 "The proper solution is to build the package for all the architectures you "
590 "have enabled. You'll need a chroot for each of the secondary "
591 "architectures. This is somewhat tiresome, even though Debian has excellent "
592 "tools for managing chroots. C<sbuild-debian-developer-setup> from the "
593 "package of the same name and C<sbuild-createchroot> from the C<sbuild> "
594 "package are good starting points."
598 #: ../dgit-user.7.pod:374
600 "Otherwise you could deinstall the packages of interest for those other "
601 "architectures with something like C<dpkg --remove libpcre3:i386>."
605 #: ../dgit-user.7.pod:378
607 "If neither of those are an option, your desperate last resort is to try "
608 "using the same version number as the official package for your own package. "
609 "(The version is controlled by C<debian/changelog> - see above). This is not "
610 "ideal because it makes it hard to tell what is installed, and because it "
611 "will mislead and confuse apt."
615 #: ../dgit-user.7.pod:386
616 msgid "With the \"same number\" approach you may still get errors like"
620 #: ../dgit-user.7.pod:390
622 "trying to overwrite shared '/usr/include/pcreposix.h', which is different "
623 "from other instances of package libpcre3-dev"
627 #: ../dgit-user.7.pod:394
629 "but passing C<--force-overwrite> to dpkg will help - assuming you know what "
634 #: ../dgit-user.7.pod:397
635 msgid "SHARING YOUR WORK"
639 #: ../dgit-user.7.pod:399
641 "The C<dgit/jessie,-security> branch (or whatever) is a normal git branch. "
642 "You can use C<git push> to publish it on any suitable git server."
646 #: ../dgit-user.7.pod:402
648 "Anyone who gets that git branch from you will be able to build binary "
649 "packages (.deb) just as you did."
653 #: ../dgit-user.7.pod:406
655 "If you want to contribute your changes back to Debian, you should probably "
656 "send them as attachments to an email to the L<Debian Bug System|https://bugs."
657 "debian.org/> (either a followup to an existing bug, or a new bug). Patches "
658 "in C<git-format-patch> format are usually very welcome."
662 #: ../dgit-user.7.pod:413
663 msgid "Source packages"
667 #: ../dgit-user.7.pod:415
669 "The git branch is not sufficient to build a source package the way Debian "
670 "does. Source packages are somewhat awkward to work with. Indeed many "
671 "plausible git histories or git trees cannot be converted into a suitable "
672 "source package. So I recommend you share your git branch instead."
676 #: ../dgit-user.7.pod:423
678 "If a git branch is not enough, and you need to provide a source package but "
679 "don't care about its format/layout (for example because some software you "
680 "have consumes source packages, not git histories) you can use this recipe "
681 "to generate a C<3.0 (native)> source package, which is just a tarball with "
682 "accompanying .dsc metadata file:"
686 #: ../dgit-user.7.pod:434
689 " % echo '3.0 (native)' >debian/source/format\n"
690 " % git commit -m 'switch to native source format' debian/source/format\n"
691 " % dgit -wgf build-source\n"
696 #: ../dgit-user.7.pod:440
698 "If you need to provide a good-looking source package, be prepared for a lot "
699 "more work. You will need to read much more, perhaps starting with L<dgit-"
700 "nmu-simple(7)>, L<dgit-sponsorship(7)> or L<dgit-maint-*(7)>"
704 #: ../dgit-user.7.pod:449 ../dgit-maint-native.7.pod:128
705 #: ../dgit-maint-merge.7.pod:493 ../dgit-maint-gbp.7.pod:138
706 msgid "dgit(1), dgit(7)"