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-user.7.pod:5 ../dgit-maint-native.7.pod:5
42 #: ../dgit-maint-merge.7.pod:5 ../dgit-maint-gbp.7.pod:5
43 #: ../dgit-maint-debrebase.7.pod:5 ../dgit-downstream-dsc.7.pod:5
44 #: ../git-debrebase.1.pod:10 ../git-debrebase.5.pod:5
49 #: ../dgit-maint-native.7.pod:37 ../dgit-maint-gbp.7.pod:16
50 #: ../dgit-maint-debrebase.7.pod:38
52 "Benefit from dgit's safety catches. In particular, ensure that your upload "
53 "always matches exactly your git HEAD."
57 #: ../dgit-maint-merge.7.pod:47 ../dgit-maint-debrebase.7.pod:61
58 msgid "INITIAL DEBIANISATION"
62 #: ../dgit-maint-merge.7.pod:49 ../dgit-maint-debrebase.7.pod:63
64 "This section explains how to start using this workflow with a new package. "
65 "It should be skipped when converting an existing package to this workflow."
69 #: ../dgit-maint-merge.7.pod:53 ../dgit-maint-merge.7.pod:335
70 #: ../dgit-maint-merge.7.pod:408 ../dgit-maint-debrebase.7.pod:67
71 #: ../dgit-maint-debrebase.7.pod:321
72 msgid "When upstream tags releases in git"
76 #: ../dgit-maint-merge.7.pod:55 ../dgit-maint-debrebase.7.pod:69
78 "Suppose that the latest stable upstream release is 1.2.2, and this has been "
79 "tagged '1.2.2' by upstream."
83 #: ../dgit-maint-merge.7.pod:60 ../dgit-maint-debrebase.7.pod:74
86 " % git clone -oupstream https://some.upstream/foo.git\n"
88 " % git verify-tag 1.2.2\n"
89 " % git reset --hard 1.2.2\n"
90 " % git branch --unset-upstream\n"
95 #: ../dgit-maint-merge.7.pod:76 ../dgit-maint-debrebase.7.pod:90
98 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
99 " % git push --follow-tags -u origin master\n"
104 #: ../dgit-maint-merge.7.pod:93 ../dgit-maint-debrebase.7.pod:102
105 msgid "Finally, you need an orig tarball:"
109 #: ../dgit-maint-merge.7.pod:97 ../dgit-maint-merge.7.pod:402
110 #: ../dgit-maint-debrebase.7.pod:106 ../dgit-maint-debrebase.7.pod:383
118 #: ../dgit-maint-merge.7.pod:101 ../dgit-maint-debrebase.7.pod:110
119 msgid "See git-deborig(1) if this fails."
123 #: ../dgit-maint-merge.7.pod:103 ../dgit-maint-debrebase.7.pod:112
125 "This tarball is ephemeral and easily regenerated, so we don't commit it "
126 "anywhere (e.g. with tools like pristine-tar(1))."
130 #: ../dgit-maint-merge.7.pod:123 ../dgit-maint-merge.7.pod:343
131 #: ../dgit-maint-merge.7.pod:433 ../dgit-maint-debrebase.7.pod:137
132 #: ../dgit-maint-debrebase.7.pod:329
133 msgid "When upstream releases only tarballs"
137 #: ../dgit-maint-merge.7.pod:130 ../dgit-maint-debrebase.7.pod:145
147 #: ../dgit-maint-merge.7.pod:136 ../dgit-maint-debrebase.7.pod:151
148 msgid "Now create I<debian/gbp.conf>:"
152 #: ../dgit-maint-merge.7.pod:140 ../dgit-maint-debrebase.7.pod:155
156 " upstream-branch = upstream\n"
157 " debian-branch = master\n"
158 " upstream-tag = %(version)s\n"
163 #: ../dgit-maint-merge.7.pod:145 ../dgit-maint-debrebase.7.pod:160
166 " sign-tags = True\n"
167 " pristine-tar = False\n"
168 " pristine-tar-commit = False\n"
173 #: ../dgit-maint-merge.7.pod:149 ../dgit-maint-debrebase.7.pod:164
177 " merge-mode = merge\n"
182 #: ../dgit-maint-merge.7.pod:154 ../dgit-maint-debrebase.7.pod:169
183 msgid "gbp-import-orig(1) requires a pre-existing upstream branch:"
187 #: ../dgit-maint-merge.7.pod:158 ../dgit-maint-debrebase.7.pod:173
190 " % git add debian/gbp.conf && git commit -m \"create gbp.conf\"\n"
191 " % git checkout --orphan upstream\n"
193 " % git commit --allow-empty -m \"initial, empty branch for upstream source\"\n"
194 " % git checkout -f master\n"
199 #: ../dgit-maint-merge.7.pod:166 ../dgit-maint-debrebase.7.pod:181
200 msgid "Then we can import the upstream version:"
204 #: ../dgit-maint-merge.7.pod:170 ../dgit-maint-debrebase.7.pod:185
207 " % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz\n"
212 #: ../dgit-maint-merge.7.pod:174 ../dgit-maint-debrebase.7.pod:189
214 "Our upstream branch cannot be pushed to B<dgit-repos>, but since we will "
215 "need it whenever we import a new upstream version, we must push it "
216 "somewhere. The usual choice is B<salsa.debian.org>:"
220 #: ../dgit-maint-merge.7.pod:180 ../dgit-maint-debrebase.7.pod:195
223 " % git remote add -f origin salsa.debian.org:Debian/foo.git\n"
224 " % git push --follow-tags -u origin master upstream\n"
229 #: ../dgit-maint-merge.7.pod:188 ../dgit-maint-debrebase.7.pod:207
230 msgid "CONVERTING AN EXISTING PACKAGE"
234 #: ../dgit-maint-merge.7.pod:190 ../dgit-maint-debrebase.7.pod:209
236 "This section explains how to convert an existing Debian package to this "
237 "workflow. It should be skipped when debianising a new package."
241 #: ../dgit-maint-merge.7.pod:229 ../dgit-maint-debrebase.7.pod:240
244 " % git remote add -f upstream https://some.upstream/foo.git\n"
249 #: ../dgit-maint-merge.7.pod:242 ../dgit-maint-debrebase.7.pod:289
251 "To achieve this, you might need to delete I<debian/source/local-options>. "
252 "One way to have dgit check your progress is to run B<dgit build-source>."
256 #: ../dgit-maint-merge.7.pod:312 ../dgit-maint-debrebase.7.pod:436
257 msgid "BUILDING AND UPLOADING"
261 #: ../dgit-maint-merge.7.pod:333 ../dgit-maint-debrebase.7.pod:319
262 msgid "Obtaining the release"
266 #: ../dgit-maint-merge.7.pod:339 ../dgit-maint-debrebase.7.pod:325
269 " % git remote update\n"
274 #: ../dgit-maint-merge.7.pod:345 ../dgit-maint-debrebase.7.pod:331
276 "You will need the I<debian/gbp.conf> from \"When upstream releases only "
277 "tarballs\", above. You will also need your upstream branch. Above, we "
278 "pushed this to B<salsa.debian.org>. You will need to clone or fetch from "
279 "there, instead of relying on B<dgit clone>/B<dgit fetch> alone."
283 #: ../dgit-maint-merge.7.pod:350 ../dgit-maint-debrebase.7.pod:336
288 #: ../dgit-maint-merge.7.pod:354 ../dgit-maint-debrebase.7.pod:340
291 " % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz\n"
296 #: ../dgit-maint-merge.7.pod:358 ../dgit-maint-debrebase.7.pod:344
297 msgid "or if you have a working watch file"
301 #: ../dgit-maint-merge.7.pod:362 ../dgit-maint-debrebase.7.pod:348
304 " % gbp import-orig --no-merge --uscan\n"
309 #: ../dgit-maint-merge.7.pod:396 ../dgit-maint-debrebase.7.pod:377
311 "If you obtained a tarball from upstream, you are ready to try a build. If "
312 "you merged a git tag from upstream, you will first need to generate a "
317 #: ../dgit-maint-merge.7.pod:406 ../dgit-maint-debrebase.7.pod:461
318 msgid "HANDLING DFSG-NON-FREE MATERIAL"
322 #: ../dgit-maint-merge.7.pod:435 ../dgit-maint-debrebase.7.pod:521
324 "The easiest way to handle this is to add a B<Files-Excluded> field to "
325 "I<debian/copyright>, and a B<uversionmangle> setting in I<debian/watch>. "
326 "See uscan(1). Alternatively, see the I<--filter> option detailed in gbp-"
331 #: ../dgit-maint-merge.7.pod:480 ../dgit-maint-gbp.7.pod:130
332 #: ../dgit-maint-debrebase.7.pod:526
333 msgid "INCORPORATING NMUS"
337 #: ../dgit-maint-merge.7.pod:495 ../dgit-maint-gbp.7.pod:140
338 #: ../dgit-maint-debrebase.7.pod:726
343 #: ../dgit-maint-merge.7.pod:497 ../dgit-maint-debrebase.7.pod:728
345 "This tutorial was written and is maintained by Sean Whitton "
346 "<spwhitton@spwhitton.name>. It contains contributions from other dgit "
347 "contributors too - see the dgit copyright file."
351 #: ../dgit-maint-gbp.7.pod:32 ../dgit-maint-debrebase.7.pod:293
352 msgid "GIT CONFIGURATION"
356 #: ../dgit-maint-debrebase.7.pod:3
358 "dgit - tutorial for package maintainers, using a workflow centered around "
363 #: ../dgit-maint-debrebase.7.pod:7
365 "This document describes elements of a workflow for maintaining a non-native "
366 "Debian package using B<dgit>. We maintain the Debian delta as a series of "
367 "git commits on our master branch. We use git-debrebase(1) to shuffle our "
368 "branch such that this series of git commits appears at the end of the "
369 "branch. All the public git history is fast-forwarding, i.e., we do not "
370 "rewrite and force-push."
374 #: ../dgit-maint-debrebase.7.pod:14
375 msgid "Some advantages of this workflow:"
379 #: ../dgit-maint-debrebase.7.pod:20
381 "Manipulate the delta queue using the full power of git-rebase(1), instead of "
382 "relying on quilt(1), and without having to switch back and forth between "
383 "patches-applied and patches-unapplied branches when committing changes and "
384 "trying to build, as with gbp-pq(1)."
388 #: ../dgit-maint-debrebase.7.pod:27
390 "If you are using 3.0 (quilt), provide your delta queue as a properly "
391 "separated series of quilt patches in the source package that you upload to "
392 "the archive (unlike with dgit-maint-merge(7))."
396 #: ../dgit-maint-debrebase.7.pod:33
398 "Avoid the git tree being dirtied by the application or unapplication of "
399 "patches, as they are always applied."
403 #: ../dgit-maint-debrebase.7.pod:43
405 "Provide your full git history in a standard format on B<dgit-repos>, where "
406 "it can benefit downstream dgit users, such as people using dgit to do an NMU "
407 "(see dgit-nmu-simple(7) and dgit-user(7))."
411 #: ../dgit-maint-debrebase.7.pod:49
413 "Minimise the amount you need to know about 3.0 (quilt) in order to maintain "
414 "Debian source packages which use that format."
418 #: ../dgit-maint-debrebase.7.pod:54
420 "This workflow is appropriate for packages where the Debian delta contains "
421 "multiple pieces which interact, or which you don't expect to be able to "
422 "upstream soon. For packages with simple and/or short-lived Debian deltas, "
423 "use of git-debrebase(1) introduces unneeded complexity. For such packages, "
424 "consider the workflow described in dgit-maint-merge(7)."
428 #: ../dgit-maint-debrebase.7.pod:82
430 "The final command detaches your master branch from the upstream remote, so "
431 "that git doesn't try to push anything there, or merge unreleased upstream "
432 "commits. To maintain a copy of your packaging branch on B<salsa.debian.org> "
433 "in addition to B<dgit-repos>, you can do something like this:"
437 #: ../dgit-maint-debrebase.7.pod:95
439 "Now go ahead and Debianise your package. Make commits on the master branch, "
440 "adding things in the I<debian/> directory, or patching the upstream source. "
441 "For technical reasons, B<it is essential that your first commit introduces "
442 "the debian/ directory containing at least one file, and does nothing else.> "
443 "In other words, make a commit introducing I<debian/> before patching the "
448 #: ../dgit-maint-debrebase.7.pod:115
449 msgid "Comparing upstream's tarball releases"
453 #: ../dgit-maint-debrebase.7.pod:119
455 "The above assumes that you know how to build the package from git and that "
456 "doing so is straightforward."
460 #: ../dgit-maint-debrebase.7.pod:122
462 "If, as a user of the upstream source, you usually build from upstream "
463 "tarball releases, rather than upstream git tags, you will sometimes find "
464 "that the git tree doesn't contain everything that is in the tarball."
468 #: ../dgit-maint-debrebase.7.pod:127
470 "Additional build steps may be needed. For example, you may need your "
471 "I<debian/rules> to run autotools."
475 #: ../dgit-maint-debrebase.7.pod:130
477 "You can compare the upstream tarball release, and upstream git tag, within "
478 "git, by importing the tarball into git as described in the next section, "
479 "using a different value for 'upstream-tag', and then using git-diff(1) to "
480 "compare the imported tarball to the release tag."
484 #: ../dgit-maint-debrebase.7.pod:139
486 "Because we want to work in git, we need a virtual upstream branch with "
487 "virtual release tags. gbp-import-orig(1) can manage this for us. To begin"
491 #: ../dgit-maint-debrebase.7.pod:200
493 "You are now ready to proceed as above, making commits to the I<debian/> "
494 "directory and to the upstream source. As above, for technical reasons, B<it "
495 "is essential that your first commit introduces the debian/ directory "
496 "containing at least one file, and does nothing else.> In other words, make a "
497 "commit introducing I<debian/> before patching the upstream source."
501 #: ../dgit-maint-debrebase.7.pod:212
503 "If you have an existing git history that you have pushed to an ordinary git "
504 "server like B<salsa.debian.org>, we start with that. If you don't already "
505 "have it locally, you'll need to clone it, and obtain the corresponding orig."
506 "tar from the archive:"
510 #: ../dgit-maint-debrebase.7.pod:219
513 " % git clone salsa.debian.org:Debian/foo\n"
515 " % dgit setup-new-tree\n"
521 #: ../dgit-maint-debrebase.7.pod:226
523 "If you don't have any existing git history, or you have history only on the "
524 "special B<dgit-repos> server, we start with B<dgit clone>:"
528 #: ../dgit-maint-debrebase.7.pod:231
531 " % dgit clone foo\n"
537 #: ../dgit-maint-debrebase.7.pod:236
538 msgid "Then we make new upstream tags available:"
542 #: ../dgit-maint-debrebase.7.pod:244
544 "We now use a B<git debrebase convert-from-*> command to convert your "
545 "existing history to the git-debrebase(5) data model. Which command you "
546 "should use depends on some facts about your repository:"
550 #: ../dgit-maint-debrebase.7.pod:250
551 msgid "(A) There is no delta queue."
555 #: ../dgit-maint-debrebase.7.pod:252
556 msgid "If there do not exist any Debian patches, use"
560 #: ../dgit-maint-debrebase.7.pod:256 ../dgit-maint-debrebase.7.pod:268
563 " % git debrebase convert-from-gbp\n"
568 #: ../dgit-maint-debrebase.7.pod:260
569 msgid "(B) There is a delta queue, and patches are unapplied."
573 #: ../dgit-maint-debrebase.7.pod:262
575 "This is the standard git-buildpackage(1) workflow: there are Debian patches, "
576 "but the upstream source is committed to git without those patches applied. "
581 #: ../dgit-maint-debrebase.7.pod:272
582 msgid "(C) There is a delta queue, and patches are applied."
586 #: ../dgit-maint-debrebase.7.pod:274
591 #: ../dgit-maint-debrebase.7.pod:278
594 " % git debrebase convert-from-dgit-view\n"
599 #: ../dgit-maint-debrebase.7.pod:284
601 "Finally, you need to ensure that your git HEAD is dgit-compatible, i.e., it "
602 "is exactly what you would get if you deleted .git, invoked B<dpkg-"
603 "buildpackage -S>, and then unpacked the resultant source package."
607 #: ../dgit-maint-debrebase.7.pod:295
609 "git-debrebase(1) does not yet support using B<git merge> to merge divergent "
610 "branches of development (see \"OTHER MERGES\" in git-debrebase(5)). You "
611 "should configure git such that B<git pull> does not try to merge:"
615 #: ../dgit-maint-debrebase.7.pod:302
618 " % git config --local pull.rebase true\n"
623 #: ../dgit-maint-debrebase.7.pod:306
625 "Now when you pull work from other Debian contributors, git will rebase your "
626 "work on top of theirs."
630 #: ../dgit-maint-debrebase.7.pod:309
632 "If you use this clone for upstream development in addition to Debian "
633 "packaging work, you may not want to set this global setting. Instead, see "
634 "the B<branch.autoSetupRebase> and B<branch.E<lt>nameE<gt>.rebase> settings "
639 #: ../dgit-maint-debrebase.7.pod:314
640 msgid "IMPORTING NEW UPSTREAM RELEASES"
644 #: ../dgit-maint-debrebase.7.pod:316
646 "There are two steps: obtaining git refs that correspond to the new release, "
647 "and importing that release using git-debrebase(1)."
651 #: ../dgit-maint-debrebase.7.pod:352
652 msgid "Importing the release"
656 #: ../dgit-maint-debrebase.7.pod:356
659 " % git debrebase new-upstream 1.2.3\n"
664 #: ../dgit-maint-debrebase.7.pod:360
666 "This invocation of git-debrebase(1) involves a git rebase. You may need to "
667 "resolve conflicts if the Debian delta queue does not apply cleanly to the "
668 "new upstream source."
672 #: ../dgit-maint-debrebase.7.pod:364
674 "If all went well, you can now review the merge of the new upstream release:"
678 #: ../dgit-maint-debrebase.7.pod:369
681 " git diff debian/1.2.2-1..HEAD -- . ':!debian'\n"
686 #: ../dgit-maint-debrebase.7.pod:373
688 "Pass I<--stat> just to see the list of changed files, which is useful to "
689 "determine whether there are any new or deleted files to may need accounting "
690 "for in your copyright file."
694 #: ../dgit-maint-debrebase.7.pod:387
695 msgid "EDITING THE DEBIAN PACKAGING"
699 #: ../dgit-maint-debrebase.7.pod:389
700 msgid "Just make commits on master that change the contents of I<debian/>."
704 #: ../dgit-maint-debrebase.7.pod:391
705 msgid "EDITING THE DELTA QUEUE"
709 #: ../dgit-maint-debrebase.7.pod:393
710 msgid "Adding new patches"
714 #: ../dgit-maint-debrebase.7.pod:395
716 "Adding new patches is straightforward: just make commits touching only files "
717 "outside of the I<debian/> directory. You can also use tools like git-"
718 "revert(1), git-am(1) and git-cherry-pick(1)."
722 #: ../dgit-maint-debrebase.7.pod:399
723 msgid "Editing patches: starting a debrebase"
727 #: ../dgit-maint-debrebase.7.pod:401
729 "git-debrebase(1) is a wrapper around git-rebase(1) which allows us to edit, "
730 "re-order and delete patches. Run"
734 #: ../dgit-maint-debrebase.7.pod:406 ../dgit-maint-debrebase.7.pod:689
737 " % git debrebase -i\n"
742 #: ../dgit-maint-debrebase.7.pod:410
744 "to start an interactive rebase. You can edit, re-order and delete commits "
745 "just as you would during B<git rebase -i>."
749 #: ../dgit-maint-debrebase.7.pod:413
750 msgid "Editing patches: finishing a debrebase"
754 #: ../dgit-maint-debrebase.7.pod:415
756 "After completing the git rebase, your branch will not be a fast-forward of "
757 "the git HEAD you had before the rebase. This means that we cannot push the "
758 "branch anywhere. If you are ready to upload, B<dgit push> or B<dgit push-"
759 "source> will take care of fixing this up for you."
763 #: ../dgit-maint-debrebase.7.pod:421
765 "If you are not yet ready to upload, and want to push your branch to a git "
766 "remote such as B<salsa.debian.org>,"
770 #: ../dgit-maint-debrebase.7.pod:426
773 " % git debrebase conclude\n"
778 #: ../dgit-maint-debrebase.7.pod:430
780 "Note that each time you conclude a debrebase you introduce a pseudomerge "
781 "into your git history, which may make it harder to read. Try to do all of "
782 "the editing of the delta queue that you think will be needed for this "
783 "editing session in a single debrebase, so that there is a single debrebase "
788 #: ../dgit-maint-debrebase.7.pod:438
790 "You can use dpkg-buildpackage(1) for test builds. When you are ready to "
791 "build for an upload, use B<dgit sbuild>, B<dgit pbuilder> or B<dgit "
796 #: ../dgit-maint-debrebase.7.pod:442
798 "Upload with B<dgit push> or B<dgit push-source>. Remember to pass I<--new> "
799 "if the package is new in the target suite."
803 #: ../dgit-maint-debrebase.7.pod:445
805 "Right before uploading, if you did not just already do so, you might want to "
806 "have git-debrebase(1) shuffle your branch such that the Debian delta queue "
807 "appears right at the tip of the branch you will push:"
811 #: ../dgit-maint-debrebase.7.pod:451
815 " % dgit push-source\n"
820 #: ../dgit-maint-debrebase.7.pod:456
821 msgid "Note that this will introduce a new pseudomerge."
825 #: ../dgit-maint-debrebase.7.pod:458
827 "After dgit pushing, be sure to git push to B<salsa.debian.org>, if you're "
832 #: ../dgit-maint-debrebase.7.pod:463
833 msgid "Illegal material"
837 #: ../dgit-maint-debrebase.7.pod:465
839 "Here we explain how to handle material that is merely DFSG-non-free. "
840 "Material which is legally dangerous (for example, files which are actually "
841 "illegal) cannot be handled this way."
845 #: ../dgit-maint-debrebase.7.pod:469
848 "If you encounter possibly-legally-dangerous material in the upstream\n"
849 "source code you should seek advice. It is often best not to make a\n"
850 "fuss on a public mailing list (at least, not at first). Instead,\n"
851 "email your archive administrators. For Debian that is\n"
852 " To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org\n"
857 #: ../dgit-maint-debrebase.7.pod:475
858 msgid "DFSG-non-free: When upstream tags releases in git"
862 #: ../dgit-maint-debrebase.7.pod:477
864 "Our approach is to maintain a DFSG-clean upstream branch, and create tags on "
865 "this branch for each release that we want to import. We then import those "
866 "tags per \"Importing the release\", above."
870 #: ../dgit-maint-debrebase.7.pod:481
871 msgid "For the first upstream release that requires DFSG filtering:"
875 #: ../dgit-maint-debrebase.7.pod:485
878 " % git checkout -b upstream-dfsg 1.2.3\n"
879 " % git rm evil.bin\n"
880 " % git commit -m \"upstream version 1.2.3 DFSG-cleaned\"\n"
881 " % git tag -s 1.2.3+dfsg\n"
882 " % git checkout master\n"
883 " % # proceed with \"Importing the release\" on 1.2.3+dfsg tag\n"
888 #: ../dgit-maint-debrebase.7.pod:494
889 msgid "And for subsequent releases (whether or not they require filtering):"
893 #: ../dgit-maint-debrebase.7.pod:498
896 " % git checkout upstream-dfsg\n"
897 " % git merge 1.2.4\n"
898 " % git rm further-evil.bin # if needed\n"
899 " % git commit -m \"upstream version 1.2.4 DFSG-cleaned\" # if needed\n"
900 " % git tag -s 1.2.4+dfsg\n"
901 " % git checkout master\n"
902 " % # proceed with \"Importing the release\" on 1.2.4+dfsg tag\n"
907 #: ../dgit-maint-debrebase.7.pod:508
909 "Our upstream-dfsg branch cannot be pushed to B<dgit-repos>, but since we "
910 "will need it whenever we import a new upstream version, we must push it "
911 "somewhere. Assuming that you have already set up an origin remote per the "
916 #: ../dgit-maint-debrebase.7.pod:515
919 " % git push --follow-tags -u origin master upstream-dfsg\n"
924 #: ../dgit-maint-debrebase.7.pod:519
925 msgid "DFSG-non-free: When upstream releases only tarballs"
929 #: ../dgit-maint-debrebase.7.pod:528
930 msgid "In the simplest case,"
934 #: ../dgit-maint-debrebase.7.pod:532
938 " % git merge --ff-only dgit/dgit/sid\n"
943 #: ../dgit-maint-debrebase.7.pod:537
945 "If that fails, because your branch and the NMUers work represent divergent "
946 "branches of development, you have a number of options. Here we describe the "
951 #: ../dgit-maint-debrebase.7.pod:541
953 "Note that you should not try to resolve the divergent branches by editing "
954 "files in I<debian/patches>. Changes there would either cause trouble, or be "
955 "overwritten by git-debrebase(1)."
959 #: ../dgit-maint-debrebase.7.pod:545
960 msgid "Rebasing your work onto the NMU"
964 #: ../dgit-maint-debrebase.7.pod:549
967 " % git rebase dgit/dgit/sid\n"
972 #: ../dgit-maint-debrebase.7.pod:553
974 "If the NMUer added new commits modifying the upstream source, you will "
975 "probably want to debrebase before your next upload to tidy those up."
979 #: ../dgit-maint-debrebase.7.pod:556
981 "For example, the NMUer might have used git-revert(1) to unapply one of your "
982 "patches. A debrebase can be used to strip both the patch and the reversion "
983 "from the delta queue."
987 #: ../dgit-maint-debrebase.7.pod:560
988 msgid "Manually applying the debdiff"
992 #: ../dgit-maint-debrebase.7.pod:562
994 "If you cannot rebase because you have already pushed to B<salsa.debian.org>, "
995 "say, you can manually apply the NMU debdiff, commit and debrebase. The next "
996 "B<dgit push> will require I<--overwrite>."
1000 #: ../dgit-maint-debrebase.7.pod:567
1001 msgid "HINTS AND TIPS"
1005 #: ../dgit-maint-debrebase.7.pod:569
1006 msgid "Minimising pseudomerges"
1010 #: ../dgit-maint-debrebase.7.pod:571
1012 "Above we noted that each time you conclude a debrebase, you introduce a "
1013 "pseudomerge into your git history, which may make it harder to read."
1017 #: ../dgit-maint-debrebase.7.pod:574
1019 "A simple convention you can use to minimise the number of pseudomerges is to "
1020 "B<git debrebase conclude> only right before you upload or push to B<salsa."
1025 #: ../dgit-maint-debrebase.7.pod:578
1027 "It is possible, though much less convenient, to reduce the number of "
1028 "pseudomerges yet further. We debrebase only (i) when importing a new "
1029 "release, and (ii) right before uploading. Instead of editing the existing "
1030 "delta queue, you append fixup commits (and reversions of commits) that alter "
1031 "the upstream source to the required state. You can push and pull to and "
1032 "from B<salsa.debian.org> during this. Just before uploading, you debrebase, "
1033 "once, to tidy everything up."
1037 #: ../dgit-maint-debrebase.7.pod:586
1038 msgid "The debian/patches directory"
1042 #: ../dgit-maint-debrebase.7.pod:588
1044 "In this workflow, I<debian/patches> is purely an output of git-"
1045 "debrebase(1). You should not make changes there. They will either cause "
1046 "trouble, or be ignored and overwritten by git-debrebase(1)."
1050 #: ../dgit-maint-debrebase.7.pod:593
1052 "I<debian/patches> will often be out-of-date because git-debrebase(1) will "
1053 "only regenerate it when it needs to. So you should not rely on the "
1054 "information in that directory. When preparing patches to forward upstream, "
1055 "you should use git-format-patch(1) on git commits, rather than sending files "
1056 "from I<debian/patches>."
1060 #: ../dgit-maint-debrebase.7.pod:599
1061 msgid "Upstream branches"
1065 #: ../dgit-maint-debrebase.7.pod:601
1066 msgid "In this workflow, we specify upstream tags rather than any branches."
1070 #: ../dgit-maint-debrebase.7.pod:603
1072 "Except when (i) upstream releases only tarballs, (ii) we require DFSG "
1073 "filtering, or (iii) you also happen to be involved in upstream development, "
1074 "we do not maintain any local branch corresponding to upstream, except "
1075 "temporary branches used to prepare patches for forwarding, and the like."
1079 #: ../dgit-maint-debrebase.7.pod:609
1081 "The idea here is that from Debian's point of view, upstream releases are "
1082 "immutable points in history. We want to make sure that we are basing our "
1083 "Debian package on a properly identified upstream version, rather than some "
1084 "arbitrary commit on some branch. Tags are more useful for this."
1088 #: ../dgit-maint-debrebase.7.pod:615
1090 "Upstream's branches remain available as the git remote tracking branches for "
1091 "your upstream remote, e.g. I<remotes/upstream/master>."
1095 #: ../dgit-maint-debrebase.7.pod:618
1096 msgid "The first ever dgit push"
1100 #: ../dgit-maint-debrebase.7.pod:620
1102 "If this is the first ever dgit push of the package, consider passing I<--"
1103 "deliberately-not-fast-forward> instead of I<--overwrite>. This avoids "
1104 "introducing a new origin commit into your git history. (This origin commit "
1105 "would represent the most recent non-dgit upload of the package, but this "
1106 "should already be represented in your git history.)"
1110 #: ../dgit-maint-debrebase.7.pod:626
1111 msgid "Inspecting the history"
1115 #: ../dgit-maint-debrebase.7.pod:628
1117 "The git history made by git-debrebase can seem complicated. Here are some "
1118 "suggestions for helpful invocations of gitk and git. They can be adapted "
1119 "for other tools like tig(1), git-log(1), magit, etc."
1123 #: ../dgit-maint-debrebase.7.pod:632
1124 msgid "History of package in Debian, disregarding history from upstream:"
1128 #: ../dgit-maint-debrebase.7.pod:636
1131 " % gitk --first-parent\n"
1136 #: ../dgit-maint-debrebase.7.pod:638
1137 msgid "In a laundered branch, the delta queue is at the top."
1141 #: ../dgit-maint-debrebase.7.pod:642
1142 msgid "History of the packaging, excluding the delta queue:"
1146 #: ../dgit-maint-debrebase.7.pod:644
1149 " % gitk :/debian :!/debian/patches\n"
1154 #: ../dgit-maint-debrebase.7.pod:646
1155 msgid "Just the delta queue (i.e. Debian's changes to upstream):"
1159 #: ../dgit-maint-debrebase.7.pod:648
1162 " % gitk --first-parent -- :/ :!/debian\n"
1167 #: ../dgit-maint-debrebase.7.pod:650
1168 msgid "Full history including old versions of the delta queue:"
1172 #: ../dgit-maint-debrebase.7.pod:654
1175 " % gitk --date-order\n"
1180 #: ../dgit-maint-debrebase.7.pod:656
1182 "The \"Declare fast forward\" commits you see have an older history (usually, "
1183 "an older delta queue) as one parent, and a newer history as the other. --"
1184 "date-order makes gitk show the delta queues in the right order."
1188 #: ../dgit-maint-debrebase.7.pod:663
1189 msgid "Complete diff since the last upload:"
1193 #: ../dgit-maint-debrebase.7.pod:667
1196 " % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches\n"
1201 #: ../dgit-maint-debrebase.7.pod:669
1202 msgid "This includes changes to upstream files."
1206 #: ../dgit-maint-debrebase.7.pod:673
1207 msgid "Interdiff of delta queue since last upload, if you really want it:"
1211 #: ../dgit-maint-debrebase.7.pod:675
1214 " % git debrebase make-patches\n"
1215 " % git diff dgit/dgit/sid..HEAD -- debian/patches\n"
1220 #: ../dgit-maint-debrebase.7.pod:678
1221 msgid "And of course there is:"
1225 #: ../dgit-maint-debrebase.7.pod:680
1228 " % git debrebase status\n"
1233 #: ../dgit-maint-debrebase.7.pod:682
1234 msgid "Alternative ways to start a debrebase"
1238 #: ../dgit-maint-debrebase.7.pod:684
1240 "Above we started an interactive debrebase by invoking git-debrebase(1) like "
1245 #: ../dgit-maint-debrebase.7.pod:693
1246 msgid "It is also possible to perform a non-interactive rebase, like this:"
1250 #: ../dgit-maint-debrebase.7.pod:697
1253 " % git debrebase -- [git-rebase options...]\n"
1258 #: ../dgit-maint-debrebase.7.pod:702
1260 "A third alternative is to have git-debrebase(1) shuffle all the Debian "
1261 "changes to the end of your branch, and then manipulate them yourself using "
1262 "git-rebase(1) directly. For example,"
1266 #: ../dgit-maint-debrebase.7.pod:708
1269 " % git debrebase\n"
1270 " % git rebase -i HEAD~5 # there are 4 Debian patches\n"
1275 #: ../dgit-maint-debrebase.7.pod:713
1277 "If you take this approach, you should be very careful not to start the "
1278 "rebase too early, including before the most recent pseudomerge. git-rebase "
1279 "without a base argument will often start the rebase too early, and should be "
1280 "avoided. Run git-debrebase instead. See also \"ILLEGAL OPERATIONS\" in git-"
1285 #: ../dgit-maint-debrebase.7.pod:724
1286 msgid "dgit(1), dgit(7), git-debrebase(1), git-debrebase(5)"