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: 2019-09-08 20:11+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 #: ../dgit-maint-bpo.7.pod:1 ../git-debrebase.1.pod:1 ../git-debrebase.5.pod:1
25 #: ../git-debpush.1.pod:1
31 #: ../dgit.1:1568 ../dgit.7:23 ../dgit-user.7.pod:447
32 #: ../dgit-nmu-simple.7.pod:137 ../dgit-maint-native.7.pod:126
33 #: ../dgit-maint-merge.7.pod:521 ../dgit-maint-gbp.7.pod:136
34 #: ../dgit-maint-debrebase.7.pod:778 ../dgit-downstream-dsc.7.pod:352
35 #: ../dgit-sponsorship.7.pod:321 ../dgit-maint-bpo.7.pod:134
36 #: ../git-debrebase.1.pod:633 ../git-debrebase.5.pod:678
37 #: ../git-debpush.1.pod:254
43 #: ../dgit-user.7.pod:5 ../dgit-maint-native.7.pod:5
44 #: ../dgit-maint-merge.7.pod:5 ../dgit-maint-gbp.7.pod:5
45 #: ../dgit-maint-debrebase.7.pod:5 ../dgit-downstream-dsc.7.pod:5
46 #: ../dgit-maint-bpo.7.pod:5 ../git-debrebase.5.pod:5
51 #: ../dgit-maint-native.7.pod:37 ../dgit-maint-gbp.7.pod:16
52 #: ../dgit-maint-debrebase.7.pod:38
54 "Benefit from dgit's safety catches. In particular, ensure that your upload "
55 "always matches exactly your git HEAD."
59 #: ../dgit-maint-merge.7.pod:47 ../dgit-maint-debrebase.7.pod:61
60 msgid "INITIAL DEBIANISATION"
64 #: ../dgit-maint-merge.7.pod:49 ../dgit-maint-debrebase.7.pod:63
66 "This section explains how to start using this workflow with a new package. "
67 "It should be skipped when converting an existing package to this workflow."
71 #: ../dgit-maint-merge.7.pod:53 ../dgit-maint-merge.7.pod:361
72 #: ../dgit-maint-merge.7.pod:438 ../dgit-maint-debrebase.7.pod:67
73 #: ../dgit-maint-debrebase.7.pod:352
74 msgid "When upstream tags releases in git"
78 #: ../dgit-maint-merge.7.pod:55 ../dgit-maint-debrebase.7.pod:69
80 "Suppose that the latest stable upstream release is 1.2.2, and this has been "
81 "tagged '1.2.2' by upstream."
85 #: ../dgit-maint-merge.7.pod:60 ../dgit-maint-debrebase.7.pod:74
88 " % git clone -oupstream https://some.upstream/foo.git\n"
90 " % git verify-tag 1.2.2\n"
91 " % git reset --hard 1.2.2\n"
92 " % git branch --unset-upstream\n"
97 #: ../dgit-maint-merge.7.pod:76 ../dgit-maint-debrebase.7.pod:90
100 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
101 " % git push --follow-tags -u origin master\n"
106 #: ../dgit-maint-merge.7.pod:93 ../dgit-maint-debrebase.7.pod:102
107 msgid "Finally, you need an orig tarball:"
111 #: ../dgit-maint-merge.7.pod:97 ../dgit-maint-merge.7.pod:432
112 #: ../dgit-maint-debrebase.7.pod:106 ../dgit-maint-debrebase.7.pod:419
120 #: ../dgit-maint-merge.7.pod:101 ../dgit-maint-debrebase.7.pod:110
121 msgid "See git-deborig(1) if this fails."
125 #: ../dgit-maint-merge.7.pod:103 ../dgit-maint-debrebase.7.pod:112
127 "This tarball is ephemeral and easily regenerated, so we don't commit it "
128 "anywhere (e.g. with tools like pristine-tar(1))."
132 #: ../dgit-maint-merge.7.pod:123 ../dgit-maint-debrebase.7.pod:137
133 msgid "Using untagged upstream commits"
137 #: ../dgit-maint-merge.7.pod:127 ../dgit-maint-debrebase.7.pod:141
139 "Sometimes upstream does not tag their releases, or you want to package an "
140 "unreleased git snapshot. In such a case you can create your own upstream "
141 "release tag, of the form B<upstream/>I<ver>, where I<ver> is the upstream "
142 "version you plan to put in I<debian/changelog>. The B<upstream/> prefix "
143 "ensures that your tag will not clash with any tags upstream later creates."
147 #: ../dgit-maint-merge.7.pod:134 ../dgit-maint-debrebase.7.pod:148
149 "For example, suppose that the latest upstream release is 1.2.2 and you want "
150 "to package git commit ab34c21 which was made on 2013-12-11. A common "
151 "convention is to use the upstream version number 1.2.2+git20131211.ab34c21 "
152 "and so you could use"
156 #: ../dgit-maint-merge.7.pod:141 ../dgit-maint-debrebase.7.pod:155
159 " % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21\n"
164 #: ../dgit-maint-merge.7.pod:145 ../dgit-maint-debrebase.7.pod:159
165 msgid "to obtain a release tag, and then proceed as above."
169 #: ../dgit-maint-merge.7.pod:149 ../dgit-maint-merge.7.pod:373
170 #: ../dgit-maint-merge.7.pod:463 ../dgit-maint-debrebase.7.pod:163
171 #: ../dgit-maint-debrebase.7.pod:364
172 msgid "When upstream releases only tarballs"
176 #: ../dgit-maint-merge.7.pod:156 ../dgit-maint-debrebase.7.pod:171
186 #: ../dgit-maint-merge.7.pod:162 ../dgit-maint-debrebase.7.pod:177
187 msgid "Now create I<debian/gbp.conf>:"
191 #: ../dgit-maint-merge.7.pod:166 ../dgit-maint-debrebase.7.pod:181
195 " upstream-branch = upstream\n"
196 " debian-branch = master\n"
197 " upstream-tag = %(version)s\n"
202 #: ../dgit-maint-merge.7.pod:171 ../dgit-maint-debrebase.7.pod:186
205 " sign-tags = True\n"
206 " pristine-tar = False\n"
207 " pristine-tar-commit = False\n"
212 #: ../dgit-maint-merge.7.pod:175 ../dgit-maint-debrebase.7.pod:190
216 " merge-mode = merge\n"
221 #: ../dgit-maint-merge.7.pod:180 ../dgit-maint-debrebase.7.pod:195
222 msgid "gbp-import-orig(1) requires a pre-existing upstream branch:"
226 #: ../dgit-maint-merge.7.pod:184 ../dgit-maint-debrebase.7.pod:199
229 " % git add debian/gbp.conf && git commit -m \"create gbp.conf\"\n"
230 " % git checkout --orphan upstream\n"
232 " % git commit --allow-empty -m \"initial, empty branch for upstream source\"\n"
233 " % git checkout -f master\n"
238 #: ../dgit-maint-merge.7.pod:192 ../dgit-maint-debrebase.7.pod:207
239 msgid "Then we can import the upstream version:"
243 #: ../dgit-maint-merge.7.pod:196 ../dgit-maint-debrebase.7.pod:211
246 " % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz\n"
251 #: ../dgit-maint-merge.7.pod:200 ../dgit-maint-debrebase.7.pod:215
253 "Our upstream branch cannot be pushed to B<dgit-repos>, but since we will "
254 "need it whenever we import a new upstream version, we must push it "
255 "somewhere. The usual choice is B<salsa.debian.org>:"
259 #: ../dgit-maint-merge.7.pod:206 ../dgit-maint-debrebase.7.pod:221
262 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
263 " % git push --follow-tags -u origin master upstream\n"
268 #: ../dgit-maint-merge.7.pod:214 ../dgit-maint-debrebase.7.pod:233
269 msgid "CONVERTING AN EXISTING PACKAGE"
273 #: ../dgit-maint-merge.7.pod:216 ../dgit-maint-debrebase.7.pod:235
275 "This section explains how to convert an existing Debian package to this "
276 "workflow. It should be skipped when debianising a new package."
280 #: ../dgit-maint-merge.7.pod:255 ../dgit-maint-debrebase.7.pod:266
283 " % git remote add -f upstream https://some.upstream/foo.git\n"
288 #: ../dgit-maint-merge.7.pod:268 ../dgit-maint-debrebase.7.pod:320
290 "To achieve this, you might need to delete I<debian/source/local-options>. "
291 "One way to have dgit check your progress is to run B<dgit build-source>."
295 #: ../dgit-maint-merge.7.pod:338 ../dgit-maint-debrebase.7.pod:472
296 msgid "BUILDING AND UPLOADING"
300 #: ../dgit-maint-merge.7.pod:359 ../dgit-maint-debrebase.7.pod:350
301 msgid "Obtaining the release"
305 #: ../dgit-maint-merge.7.pod:365 ../dgit-maint-debrebase.7.pod:356
308 " % git fetch --tags upstream\n"
313 #: ../dgit-maint-merge.7.pod:369 ../dgit-maint-debrebase.7.pod:360
315 "If you want to package an untagged upstream commit (because upstream does "
316 "not tag releases or because you want to package an upstream development "
317 "snapshot), see \"Using untagged upstream commits\" above."
321 #: ../dgit-maint-merge.7.pod:375 ../dgit-maint-debrebase.7.pod:366
323 "You will need the I<debian/gbp.conf> from \"When upstream releases only "
324 "tarballs\", above. You will also need your upstream branch. Above, we "
325 "pushed this to B<salsa.debian.org>. You will need to clone or fetch from "
326 "there, instead of relying on B<dgit clone>/B<dgit fetch> alone."
330 #: ../dgit-maint-merge.7.pod:380 ../dgit-maint-debrebase.7.pod:371
335 #: ../dgit-maint-merge.7.pod:384 ../dgit-maint-debrebase.7.pod:375
338 " % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz\n"
343 #: ../dgit-maint-merge.7.pod:388 ../dgit-maint-debrebase.7.pod:379
344 msgid "or if you have a working watch file"
348 #: ../dgit-maint-merge.7.pod:392 ../dgit-maint-debrebase.7.pod:383
351 " % gbp import-orig --no-merge --uscan\n"
356 #: ../dgit-maint-merge.7.pod:426 ../dgit-maint-debrebase.7.pod:413
358 "If you obtained a tarball from upstream, you are ready to try a build. If "
359 "you merged a git tag from upstream, you will first need to generate a "
364 #: ../dgit-maint-merge.7.pod:436 ../dgit-maint-debrebase.7.pod:503
365 msgid "HANDLING DFSG-NON-FREE MATERIAL"
369 #: ../dgit-maint-merge.7.pod:465 ../dgit-maint-debrebase.7.pod:577
371 "The easiest way to handle this is to add a B<Files-Excluded> field to "
372 "I<debian/copyright>, and a B<uversionmangle> setting in I<debian/watch>. "
373 "See uscan(1). Alternatively, see the I<--filter> option detailed in gbp-"
378 #: ../dgit-maint-merge.7.pod:510 ../dgit-maint-gbp.7.pod:130
379 #: ../dgit-maint-debrebase.7.pod:582
380 msgid "INCORPORATING NMUS"
384 #: ../dgit-maint-merge.7.pod:525 ../dgit-maint-gbp.7.pod:140
385 #: ../dgit-maint-debrebase.7.pod:782 ../dgit-maint-bpo.7.pod:138
386 #: ../git-debpush.1.pod:259
391 #: ../dgit-maint-merge.7.pod:527 ../dgit-maint-debrebase.7.pod:784
393 "This tutorial was written and is maintained by Sean Whitton "
394 "<spwhitton@spwhitton.name>. It contains contributions from other dgit "
395 "contributors too - see the dgit copyright file."
399 #: ../dgit-maint-gbp.7.pod:32 ../dgit-maint-debrebase.7.pod:324
400 msgid "GIT CONFIGURATION"
404 #: ../dgit-maint-debrebase.7.pod:3
406 "dgit - tutorial for package maintainers, using a workflow centered around "
411 #: ../dgit-maint-debrebase.7.pod:7
413 "This document describes elements of a workflow for maintaining a non-native "
414 "Debian package using B<dgit>. We maintain the Debian delta as a series of "
415 "git commits on our master branch. We use git-debrebase(1) to shuffle our "
416 "branch such that this series of git commits appears at the end of the "
417 "branch. All the public git history is fast-forwarding, i.e., we do not "
418 "rewrite and force-push."
422 #: ../dgit-maint-debrebase.7.pod:14
423 msgid "Some advantages of this workflow:"
427 #: ../dgit-maint-debrebase.7.pod:20
429 "Manipulate the delta queue using the full power of git-rebase(1), instead of "
430 "relying on quilt(1), and without having to switch back and forth between "
431 "patches-applied and patches-unapplied branches when committing changes and "
432 "trying to build, as with gbp-pq(1)."
436 #: ../dgit-maint-debrebase.7.pod:27
438 "If you are using 3.0 (quilt), provide your delta queue as a properly "
439 "separated series of quilt patches in the source package that you upload to "
440 "the archive (unlike with dgit-maint-merge(7))."
444 #: ../dgit-maint-debrebase.7.pod:33
446 "Avoid the git tree being dirtied by the application or unapplication of "
447 "patches, as they are always applied."
451 #: ../dgit-maint-debrebase.7.pod:43
453 "Provide your full git history in a standard format on B<dgit-repos>, where "
454 "it can benefit downstream dgit users, such as people using dgit to do an NMU "
455 "(see dgit-nmu-simple(7) and dgit-user(7))."
459 #: ../dgit-maint-debrebase.7.pod:49
461 "Minimise the amount you need to know about 3.0 (quilt) in order to maintain "
462 "Debian source packages which use that format."
466 #: ../dgit-maint-debrebase.7.pod:54
468 "This workflow is appropriate for packages where the Debian delta contains "
469 "multiple pieces which interact, or which you don't expect to be able to "
470 "upstream soon. For packages with simple and/or short-lived Debian deltas, "
471 "use of git-debrebase(1) introduces unneeded complexity. For such packages, "
472 "consider the workflow described in dgit-maint-merge(7)."
476 #: ../dgit-maint-debrebase.7.pod:82
478 "The final command detaches your master branch from the upstream remote, so "
479 "that git doesn't try to push anything there, or merge unreleased upstream "
480 "commits. To maintain a copy of your packaging branch on B<salsa.debian.org> "
481 "in addition to B<dgit-repos>, you can do something like this:"
485 #: ../dgit-maint-debrebase.7.pod:95
487 "Now go ahead and Debianise your package. Make commits on the master branch, "
488 "adding things in the I<debian/> directory, or patching the upstream source. "
489 "For technical reasons, B<it is essential that your first commit introduces "
490 "the debian/ directory containing at least one file, and does nothing else.> "
491 "In other words, make a commit introducing I<debian/> before patching the "
496 #: ../dgit-maint-debrebase.7.pod:115
497 msgid "Comparing upstream's tarball releases"
501 #: ../dgit-maint-debrebase.7.pod:119
503 "The above assumes that you know how to build the package from git and that "
504 "doing so is straightforward."
508 #: ../dgit-maint-debrebase.7.pod:122
510 "If, as a user of the upstream source, you usually build from upstream "
511 "tarball releases, rather than upstream git tags, you will sometimes find "
512 "that the git tree doesn't contain everything that is in the tarball."
516 #: ../dgit-maint-debrebase.7.pod:127
518 "Additional build steps may be needed. For example, you may need your "
519 "I<debian/rules> to run autotools."
523 #: ../dgit-maint-debrebase.7.pod:130
525 "You can compare the upstream tarball release, and upstream git tag, within "
526 "git, by importing the tarball into git as described in the next section, "
527 "using a different value for 'upstream-tag', and then using git-diff(1) to "
528 "compare the imported tarball to the release tag."
532 #: ../dgit-maint-debrebase.7.pod:165
534 "Because we want to work in git, we need a virtual upstream branch with "
535 "virtual release tags. gbp-import-orig(1) can manage this for us. To begin"
539 #: ../dgit-maint-debrebase.7.pod:226
541 "You are now ready to proceed as above, making commits to the I<debian/> "
542 "directory and to the upstream source. As above, for technical reasons, B<it "
543 "is essential that your first commit introduces the debian/ directory "
544 "containing at least one file, and does nothing else.> In other words, make a "
545 "commit introducing I<debian/> before patching the upstream source."
549 #: ../dgit-maint-debrebase.7.pod:238
551 "If you have an existing git history that you have pushed to an ordinary git "
552 "server like B<salsa.debian.org>, we start with that. If you don't already "
553 "have it locally, you'll need to clone it, and obtain the corresponding orig."
554 "tar from the archive:"
558 #: ../dgit-maint-debrebase.7.pod:245
561 " % git clone salsa.debian.org:Debian/foo\n"
563 " % dgit setup-new-tree\n"
569 #: ../dgit-maint-debrebase.7.pod:252
571 "If you don't have any existing git history, or you have history only on the "
572 "special B<dgit-repos> server, we start with B<dgit clone>:"
576 #: ../dgit-maint-debrebase.7.pod:257
579 " % dgit clone foo\n"
585 #: ../dgit-maint-debrebase.7.pod:262
586 msgid "Then we make new upstream tags available:"
590 #: ../dgit-maint-debrebase.7.pod:270
592 "We now use a B<git debrebase convert-from-*> command to convert your "
593 "existing history to the git-debrebase(5) data model. Which command you "
594 "should use depends on some facts about your repository:"
598 #: ../dgit-maint-debrebase.7.pod:276
599 msgid "(A) There is no delta queue."
603 #: ../dgit-maint-debrebase.7.pod:278
604 msgid "If there do not exist any Debian patches, use"
608 #: ../dgit-maint-debrebase.7.pod:282 ../dgit-maint-debrebase.7.pod:294
611 " % git debrebase convert-from-gbp\n"
616 #: ../dgit-maint-debrebase.7.pod:286
617 msgid "(B) There is a delta queue, and patches are unapplied."
621 #: ../dgit-maint-debrebase.7.pod:288
623 "This is the standard git-buildpackage(1) workflow: there are Debian patches, "
624 "but the upstream source is committed to git without those patches applied. "
629 #: ../dgit-maint-debrebase.7.pod:298
631 "If you were not previously using dgit to upload your package (i.e. you were "
632 "not using the workflow described in dgit-maint-gbp(7)), and you happen to "
633 "have run B<dgit fetch sid> in this clone of the repository, you will need to "
634 "pass I<--fdiverged> to this command."
638 #: ../dgit-maint-debrebase.7.pod:303
639 msgid "(C) There is a delta queue, and patches are applied."
643 #: ../dgit-maint-debrebase.7.pod:305
648 #: ../dgit-maint-debrebase.7.pod:309
651 " % git debrebase convert-from-dgit-view\n"
656 #: ../dgit-maint-debrebase.7.pod:315
658 "Finally, you need to ensure that your git HEAD is dgit-compatible, i.e., it "
659 "is exactly what you would get if you deleted .git, invoked B<dpkg-"
660 "buildpackage -S>, and then unpacked the resultant source package."
664 #: ../dgit-maint-debrebase.7.pod:326
666 "git-debrebase(1) does not yet support using B<git merge> to merge divergent "
667 "branches of development (see \"OTHER MERGES\" in git-debrebase(5)). You "
668 "should configure git such that B<git pull> does not try to merge:"
672 #: ../dgit-maint-debrebase.7.pod:333
675 " % git config --local pull.rebase true\n"
680 #: ../dgit-maint-debrebase.7.pod:337
682 "Now when you pull work from other Debian contributors, git will rebase your "
683 "work on top of theirs."
687 #: ../dgit-maint-debrebase.7.pod:340
689 "If you use this clone for upstream development in addition to Debian "
690 "packaging work, you may not want to set this global setting. Instead, see "
691 "the B<branch.autoSetupRebase> and B<branch.E<lt>nameE<gt>.rebase> settings "
696 #: ../dgit-maint-debrebase.7.pod:345
697 msgid "IMPORTING NEW UPSTREAM RELEASES"
701 #: ../dgit-maint-debrebase.7.pod:347
703 "There are two steps: obtaining git refs that correspond to the new release, "
704 "and importing that release using git-debrebase(1)."
708 #: ../dgit-maint-debrebase.7.pod:387
709 msgid "Importing the release"
713 #: ../dgit-maint-debrebase.7.pod:391
716 " % git debrebase new-upstream 1.2.3\n"
721 #: ../dgit-maint-debrebase.7.pod:395
723 "This invocation of git-debrebase(1) involves a git rebase. You may need to "
724 "resolve conflicts if the Debian delta queue does not apply cleanly to the "
725 "new upstream source."
729 #: ../dgit-maint-debrebase.7.pod:399
731 "If all went well, you can now review the merge of the new upstream release:"
735 #: ../dgit-maint-debrebase.7.pod:404
738 " git diff debian/1.2.2-1..HEAD -- . ':!debian'\n"
743 #: ../dgit-maint-debrebase.7.pod:408
745 "Also, diff with I<--name-status> and I<--diff-filter=ADR> to see just the "
746 "list of added or removed files, which is useful to determine whether there "
747 "are any new or deleted files that may need accounting for in your copyright "
752 #: ../dgit-maint-debrebase.7.pod:423
753 msgid "EDITING THE DEBIAN PACKAGING"
757 #: ../dgit-maint-debrebase.7.pod:425
758 msgid "Just make commits on master that change the contents of I<debian/>."
762 #: ../dgit-maint-debrebase.7.pod:427
763 msgid "EDITING THE DELTA QUEUE"
767 #: ../dgit-maint-debrebase.7.pod:429
768 msgid "Adding new patches"
772 #: ../dgit-maint-debrebase.7.pod:431
774 "Adding new patches is straightforward: just make commits touching only files "
775 "outside of the I<debian/> directory. You can also use tools like git-"
776 "revert(1), git-am(1) and git-cherry-pick(1)."
780 #: ../dgit-maint-debrebase.7.pod:435
781 msgid "Editing patches: starting a debrebase"
785 #: ../dgit-maint-debrebase.7.pod:437
787 "git-debrebase(1) is a wrapper around git-rebase(1) which allows us to edit, "
788 "re-order and delete patches. Run"
792 #: ../dgit-maint-debrebase.7.pod:442 ../dgit-maint-debrebase.7.pod:745
795 " % git debrebase -i\n"
800 #: ../dgit-maint-debrebase.7.pod:446
802 "to start an interactive rebase. You can edit, re-order and delete commits "
803 "just as you would during B<git rebase -i>."
807 #: ../dgit-maint-debrebase.7.pod:449
808 msgid "Editing patches: finishing a debrebase"
812 #: ../dgit-maint-debrebase.7.pod:451
814 "After completing the git rebase, your branch will not be a fast-forward of "
815 "the git HEAD you had before the rebase. This means that we cannot push the "
816 "branch anywhere. If you are ready to upload, B<dgit push> or B<dgit push-"
817 "source> will take care of fixing this up for you."
821 #: ../dgit-maint-debrebase.7.pod:457
823 "If you are not yet ready to upload, and want to push your branch to a git "
824 "remote such as B<salsa.debian.org>,"
828 #: ../dgit-maint-debrebase.7.pod:462
831 " % git debrebase conclude\n"
836 #: ../dgit-maint-debrebase.7.pod:466
838 "Note that each time you conclude a debrebase you introduce a pseudomerge "
839 "into your git history, which may make it harder to read. Try to do all of "
840 "the editing of the delta queue that you think will be needed for this "
841 "editing session in a single debrebase, so that there is a single debrebase "
846 #: ../dgit-maint-debrebase.7.pod:474
848 "You can use dpkg-buildpackage(1) for test builds. When you are ready to "
849 "build for an upload, use B<dgit sbuild>, B<dgit pbuilder> or B<dgit "
854 #: ../dgit-maint-debrebase.7.pod:478
856 "Upload with B<dgit push> or B<dgit push-source>. Remember to pass I<--new> "
857 "if the package is new in the target suite."
861 #: ../dgit-maint-debrebase.7.pod:481
863 "In some cases where you used B<git debrebase convert-from-gbp> since the "
864 "last upload, it is not possible for dgit to make your history fast-"
865 "forwarding from the history on B<dgit-repos>. In such cases you will have "
866 "to pass I<--overwrite> to dgit. git-debrebase will normally tell you if "
867 "this will be needed."
871 #: ../dgit-maint-debrebase.7.pod:487
873 "Right before uploading, if you did not just already do so, you might want to "
874 "have git-debrebase(1) shuffle your branch such that the Debian delta queue "
875 "appears right at the tip of the branch you will push:"
879 #: ../dgit-maint-debrebase.7.pod:493
883 " % dgit push-source\n"
888 #: ../dgit-maint-debrebase.7.pod:498
889 msgid "Note that this will introduce a new pseudomerge."
893 #: ../dgit-maint-debrebase.7.pod:500
895 "After dgit pushing, be sure to git push to B<salsa.debian.org>, if you're "
900 #: ../dgit-maint-debrebase.7.pod:505
901 msgid "Illegal material"
905 #: ../dgit-maint-debrebase.7.pod:507
907 "Here we explain how to handle material that is merely DFSG-non-free. "
908 "Material which is legally dangerous (for example, files which are actually "
909 "illegal) cannot be handled this way."
913 #: ../dgit-maint-debrebase.7.pod:511
916 "If you encounter possibly-legally-dangerous material in the upstream\n"
917 "source code you should seek advice. It is often best not to make a\n"
918 "fuss on a public mailing list (at least, not at first). Instead,\n"
919 "email your archive administrators. For Debian that is\n"
920 " To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org\n"
925 #: ../dgit-maint-debrebase.7.pod:517
926 msgid "DFSG-non-free: When upstream tags releases in git"
930 #: ../dgit-maint-debrebase.7.pod:519
932 "Our approach is to maintain a DFSG-clean upstream branch, and create tags on "
933 "this branch for each release that we want to import. We then import those "
934 "tags per \"Importing the release\", above. In the case of a new package, we "
935 "base our initial Debianisation on our first DFSG-clean tag."
939 #: ../dgit-maint-debrebase.7.pod:525
940 msgid "For the first upstream release that requires DFSG filtering:"
944 #: ../dgit-maint-debrebase.7.pod:529
947 " % git checkout -b upstream-dfsg 1.2.3\n"
948 " % git rm evil.bin\n"
949 " % git commit -m \"upstream version 1.2.3 DFSG-cleaned\"\n"
950 " % git tag -s 1.2.3+dfsg\n"
951 " % git checkout master\n"
956 #: ../dgit-maint-debrebase.7.pod:537
958 "Now either proceed with \"Importing the release\" on the 1.2.3+dfsg tag, or "
959 "in the case of a new package,"
963 #: ../dgit-maint-debrebase.7.pod:542
966 " % git branch --unset-upstream\n"
967 " % git reset --hard 1.2.3+dfsg\n"
972 #: ../dgit-maint-debrebase.7.pod:547
973 msgid "and proceed with \"INITIAL DEBIANISATION\"."
977 #: ../dgit-maint-debrebase.7.pod:549
979 "For subsequent releases (whether or not they require additional filtering):"
983 #: ../dgit-maint-debrebase.7.pod:554
986 " % git checkout upstream-dfsg\n"
987 " % git merge 1.2.4\n"
988 " % git rm further-evil.bin # if needed\n"
989 " % git commit -m \"upstream version 1.2.4 DFSG-cleaned\" # if needed\n"
990 " % git tag -s 1.2.4+dfsg\n"
991 " % git checkout master\n"
992 " % # proceed with \"Importing the release\" on 1.2.4+dfsg tag\n"
997 #: ../dgit-maint-debrebase.7.pod:564
999 "Our upstream-dfsg branch cannot be pushed to B<dgit-repos>, but since we "
1000 "will need it whenever we import a new upstream version, we must push it "
1001 "somewhere. Assuming that you have already set up an origin remote per the "
1006 #: ../dgit-maint-debrebase.7.pod:571
1009 " % git push --follow-tags -u origin master upstream-dfsg\n"
1014 #: ../dgit-maint-debrebase.7.pod:575
1015 msgid "DFSG-non-free: When upstream releases only tarballs"
1019 #: ../dgit-maint-debrebase.7.pod:584
1020 msgid "In the simplest case,"
1024 #: ../dgit-maint-debrebase.7.pod:588
1028 " % git merge --ff-only dgit/dgit/sid\n"
1033 #: ../dgit-maint-debrebase.7.pod:593
1035 "If that fails, because your branch and the NMUers' work represent divergent "
1036 "branches of development, you have a number of options. Here we describe the "
1041 #: ../dgit-maint-debrebase.7.pod:597
1043 "Note that you should not try to resolve the divergent branches by editing "
1044 "files in I<debian/patches>. Changes there would either cause trouble, or be "
1045 "overwritten by git-debrebase(1)."
1049 #: ../dgit-maint-debrebase.7.pod:601
1050 msgid "Rebasing your work onto the NMU"
1054 #: ../dgit-maint-debrebase.7.pod:605
1057 " % git rebase dgit/dgit/sid\n"
1062 #: ../dgit-maint-debrebase.7.pod:609
1064 "If the NMUer added new commits modifying the upstream source, you will "
1065 "probably want to debrebase before your next upload to tidy those up."
1069 #: ../dgit-maint-debrebase.7.pod:612
1071 "For example, the NMUer might have used git-revert(1) to unapply one of your "
1072 "patches. A debrebase can be used to strip both the patch and the reversion "
1073 "from the delta queue."
1077 #: ../dgit-maint-debrebase.7.pod:616
1078 msgid "Manually applying the debdiff"
1082 #: ../dgit-maint-debrebase.7.pod:618
1084 "If you cannot rebase because you have already pushed to B<salsa.debian.org>, "
1085 "say, you can manually apply the NMU debdiff, commit and debrebase. The next "
1086 "B<dgit push> will require I<--overwrite>."
1090 #: ../dgit-maint-debrebase.7.pod:623
1091 msgid "HINTS AND TIPS"
1095 #: ../dgit-maint-debrebase.7.pod:625
1096 msgid "Minimising pseudomerges"
1100 #: ../dgit-maint-debrebase.7.pod:627
1102 "Above we noted that each time you conclude a debrebase, you introduce a "
1103 "pseudomerge into your git history, which may make it harder to read."
1107 #: ../dgit-maint-debrebase.7.pod:630
1109 "A simple convention you can use to minimise the number of pseudomerges is to "
1110 "B<git debrebase conclude> only right before you upload or push to B<salsa."
1115 #: ../dgit-maint-debrebase.7.pod:634
1117 "It is possible, though much less convenient, to reduce the number of "
1118 "pseudomerges yet further. We debrebase only (i) when importing a new "
1119 "release, and (ii) right before uploading. Instead of editing the existing "
1120 "delta queue, you append fixup commits (and reversions of commits) that alter "
1121 "the upstream source to the required state. You can push and pull to and "
1122 "from B<salsa.debian.org> during this. Just before uploading, you debrebase, "
1123 "once, to tidy everything up."
1127 #: ../dgit-maint-debrebase.7.pod:642
1128 msgid "The debian/patches directory"
1132 #: ../dgit-maint-debrebase.7.pod:644
1134 "In this workflow, I<debian/patches> is purely an output of git-"
1135 "debrebase(1). You should not make changes there. They will either cause "
1136 "trouble, or be ignored and overwritten by git-debrebase(1)."
1140 #: ../dgit-maint-debrebase.7.pod:649
1142 "I<debian/patches> will often be out-of-date because git-debrebase(1) will "
1143 "only regenerate it when it needs to. So you should not rely on the "
1144 "information in that directory. When preparing patches to forward upstream, "
1145 "you should use git-format-patch(1) on git commits, rather than sending files "
1146 "from I<debian/patches>."
1150 #: ../dgit-maint-debrebase.7.pod:655
1151 msgid "Upstream branches"
1155 #: ../dgit-maint-debrebase.7.pod:657
1156 msgid "In this workflow, we specify upstream tags rather than any branches."
1160 #: ../dgit-maint-debrebase.7.pod:659
1162 "Except when (i) upstream releases only tarballs, (ii) we require DFSG "
1163 "filtering, or (iii) you also happen to be involved in upstream development, "
1164 "we do not maintain any local branch corresponding to upstream, except "
1165 "temporary branches used to prepare patches for forwarding, and the like."
1169 #: ../dgit-maint-debrebase.7.pod:665
1171 "The idea here is that from Debian's point of view, upstream releases are "
1172 "immutable points in history. We want to make sure that we are basing our "
1173 "Debian package on a properly identified upstream version, rather than some "
1174 "arbitrary commit on some branch. Tags are more useful for this."
1178 #: ../dgit-maint-debrebase.7.pod:671
1180 "Upstream's branches remain available as the git remote tracking branches for "
1181 "your upstream remote, e.g. I<remotes/upstream/master>."
1185 #: ../dgit-maint-debrebase.7.pod:674
1186 msgid "The first ever dgit push"
1190 #: ../dgit-maint-debrebase.7.pod:676
1192 "If this is the first ever dgit push of the package, consider passing I<--"
1193 "deliberately-not-fast-forward> instead of I<--overwrite>. This avoids "
1194 "introducing a new origin commit into your git history. (This origin commit "
1195 "would represent the most recent non-dgit upload of the package, but this "
1196 "should already be represented in your git history.)"
1200 #: ../dgit-maint-debrebase.7.pod:682
1201 msgid "Inspecting the history"
1205 #: ../dgit-maint-debrebase.7.pod:684
1207 "The git history made by git-debrebase can seem complicated. Here are some "
1208 "suggestions for helpful invocations of gitk and git. They can be adapted "
1209 "for other tools like tig(1), git-log(1), magit, etc."
1213 #: ../dgit-maint-debrebase.7.pod:688
1214 msgid "History of package in Debian, disregarding history from upstream:"
1218 #: ../dgit-maint-debrebase.7.pod:692
1221 " % gitk --first-parent\n"
1226 #: ../dgit-maint-debrebase.7.pod:694
1227 msgid "In a laundered branch, the delta queue is at the top."
1231 #: ../dgit-maint-debrebase.7.pod:698
1232 msgid "History of the packaging, excluding the delta queue:"
1236 #: ../dgit-maint-debrebase.7.pod:700
1239 " % gitk :/debian :!/debian/patches\n"
1244 #: ../dgit-maint-debrebase.7.pod:702
1245 msgid "Just the delta queue (i.e. Debian's changes to upstream):"
1249 #: ../dgit-maint-debrebase.7.pod:704
1252 " % gitk --first-parent -- :/ :!/debian\n"
1257 #: ../dgit-maint-debrebase.7.pod:706
1258 msgid "Full history including old versions of the delta queue:"
1262 #: ../dgit-maint-debrebase.7.pod:710
1265 " % gitk --date-order\n"
1270 #: ../dgit-maint-debrebase.7.pod:712
1272 "The \"Declare fast forward\" commits you see have an older history (usually, "
1273 "an older delta queue) as one parent, and a newer history as the other. --"
1274 "date-order makes gitk show the delta queues in the right order."
1278 #: ../dgit-maint-debrebase.7.pod:719
1279 msgid "Complete diff since the last upload:"
1283 #: ../dgit-maint-debrebase.7.pod:723
1286 " % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches\n"
1291 #: ../dgit-maint-debrebase.7.pod:725
1292 msgid "This includes changes to upstream files."
1296 #: ../dgit-maint-debrebase.7.pod:729
1297 msgid "Interdiff of delta queue since last upload, if you really want it:"
1301 #: ../dgit-maint-debrebase.7.pod:731
1304 " % git debrebase make-patches\n"
1305 " % git diff dgit/dgit/sid..HEAD -- debian/patches\n"
1310 #: ../dgit-maint-debrebase.7.pod:734
1311 msgid "And of course there is:"
1315 #: ../dgit-maint-debrebase.7.pod:736
1318 " % git debrebase status\n"
1323 #: ../dgit-maint-debrebase.7.pod:738
1324 msgid "Alternative ways to start a debrebase"
1328 #: ../dgit-maint-debrebase.7.pod:740
1330 "Above we started an interactive debrebase by invoking git-debrebase(1) like "
1335 #: ../dgit-maint-debrebase.7.pod:749
1336 msgid "It is also possible to perform a non-interactive rebase, like this:"
1340 #: ../dgit-maint-debrebase.7.pod:753
1343 " % git debrebase -- [git-rebase options...]\n"
1348 #: ../dgit-maint-debrebase.7.pod:758
1350 "A third alternative is to have git-debrebase(1) shuffle all the Debian "
1351 "changes to the end of your branch, and then manipulate them yourself using "
1352 "git-rebase(1) directly. For example,"
1356 #: ../dgit-maint-debrebase.7.pod:764
1359 " % git debrebase\n"
1360 " % git rebase -i HEAD~5 # there are 4 Debian patches\n"
1365 #: ../dgit-maint-debrebase.7.pod:769
1367 "If you take this approach, you should be very careful not to start the "
1368 "rebase too early, including before the most recent pseudomerge. git-rebase "
1369 "without a base argument will often start the rebase too early, and should be "
1370 "avoided. Run git-debrebase instead. See also \"ILLEGAL OPERATIONS\" in git-"
1375 #: ../dgit-maint-debrebase.7.pod:780
1376 msgid "dgit(1), dgit(7), git-debrebase(1), git-debrebase(5)"