Package: dgit Version: 6.10 Severity: minor Tags: patch Hello,
On Fri 24 Aug 2018 at 03:48PM +0100, Ian Jackson wrote: > During a conversation on pkg-xen-devel, it became evident that there > is too little advice on how to examine things when using > git-debrebase. There's a lot of advice on how to change things, but > little on how to see what they're currently like. Without this advice > the whole workflow can be a bit disorienting. > > I wrote some text in an email to pkg-xen-devel (see below). I think > something like this should be in some manpage. > > Should this be in dgit-maint-debrebase(7) ? Or git-debrebase(5) ? > Do we need a git-debrebase(7) too ? I'm very happy to see this information published somewhere. I do not like having it as a top level heading in dgit-maint-debrebase(7), however -- I do not see it as part of the core workflow described by the other top level headings. I would like to suggest demoting it into the HINTS AND TIPS section of that manpage. Here are patches. We might move it to git-debrebase(7) at a later date if we found other things to write about in that page. -- Sean Whitton
From 01248929c4806944f7fbc0fcbffb0656472848d3 Mon Sep 17 00:00:00 2001 From: Sean Whitton <[email protected]> Date: Sun, 26 Aug 2018 09:13:27 -0700 Subject: [PATCH 1/3] dgit-maint-debrebase(7): demote "Inspecting the history" Signed-off-by: Sean Whitton <[email protected]> --- dgit-maint-debrebase.7.pod | 94 +++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index b4330f9..675e2f3 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -458,53 +458,6 @@ Note that this will introduce a new pseudomerge. After dgit pushing, be sure to git push to B<salsa.debian.org>, if you're using that. -=head1 INSPECTING THE HISTORY - -The git history made by git-debrebase can seem complicated. -Here are some suggestions for helpful invocations of gitk and git. -They can be adapted for other tools like tig, git log, etc. - -=over - -=item History of package in Debian (disregarding history from upstream): - - % gitk --first-parent - -In a laundered branch, the delta queue is at the top. - -=item History of the packaging (excluding the delta queue) - - % gitk :/debian :!/debian/patches - -=item Just the delta queue (ie, Debian's changes to upstream): - - % gitk --first-parent -- :/ :!/debian - -=item Full history including old versions of the delta queue: - - % gitk --date-order - -The "Declare fast forward" commits you see have an older history -(usually, an older delta queue) as one parent, -and a newer history as the other. ---date-order makes gitk show the delta queues in the right order. - -=item Show complete diff since the last upload: - - % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches -(Includes changes to upstream files.) - -=item Interdiff of delta queue since last upload, if you really want that: - - % git debrebase make-patches - % git diff dgit/dgit/sid..HEAD -- debian/patches - -=back - -Also of course there is - - % git debrebase status - =head1 HANDLING DFSG-NON-FREE MATERIAL =head2 Illegal material @@ -670,6 +623,53 @@ avoids introducing a new origin commit into your git history. (This origin commit would represent the most recent non-dgit upload of the package, but this should already be represented in your git history.) +=head2 Inspecting the history + +The git history made by git-debrebase can seem complicated. +Here are some suggestions for helpful invocations of gitk and git. +They can be adapted for other tools like tig, git log, etc. + +=over + +=item History of package in Debian (disregarding history from upstream): + + % gitk --first-parent + +In a laundered branch, the delta queue is at the top. + +=item History of the packaging (excluding the delta queue) + + % gitk :/debian :!/debian/patches + +=item Just the delta queue (ie, Debian's changes to upstream): + + % gitk --first-parent -- :/ :!/debian + +=item Full history including old versions of the delta queue: + + % gitk --date-order + +The "Declare fast forward" commits you see have an older history +(usually, an older delta queue) as one parent, +and a newer history as the other. +--date-order makes gitk show the delta queues in the right order. + +=item Show complete diff since the last upload: + + % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches +(Includes changes to upstream files.) + +=item Interdiff of delta queue since last upload, if you really want that: + + % git debrebase make-patches + % git diff dgit/dgit/sid..HEAD -- debian/patches + +=back + +Also of course there is + + % git debrebase status + =head2 Alternative ways to start a debrebase Above we started an interactive debrebase by invoking git-debrebase(1) -- 2.11.0
From a026eb4196331a76f9b20f74db5f8e69e882d3bf Mon Sep 17 00:00:00 2001 From: Sean Whitton <[email protected]> Date: Sun, 26 Aug 2018 09:24:13 -0700 Subject: [PATCH 2/3] dgit-maint-debrebase(7): Avoid some uses of =item Commands for the user to type into their shell should have empty lines above and below them; this ensures that. Admittedly while making the POD source harder to read. Signed-off-by: Sean Whitton <[email protected]> --- dgit-maint-debrebase.7.pod | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index 675e2f3..cc393b5 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -629,23 +629,27 @@ The git history made by git-debrebase can seem complicated. Here are some suggestions for helpful invocations of gitk and git. They can be adapted for other tools like tig, git log, etc. -=over +History of package in Debian, disregarding history from upstream: -=item History of package in Debian (disregarding history from upstream): +=over % gitk --first-parent In a laundered branch, the delta queue is at the top. -=item History of the packaging (excluding the delta queue) +=back + +History of the packaging, excluding the delta queue: % gitk :/debian :!/debian/patches -=item Just the delta queue (ie, Debian's changes to upstream): +Just the delta queue (i.e. Debian's changes to upstream): % gitk --first-parent -- :/ :!/debian -=item Full history including old versions of the delta queue: +Full history including old versions of the delta queue: + +=over % gitk --date-order @@ -654,18 +658,22 @@ The "Declare fast forward" commits you see have an older history and a newer history as the other. --date-order makes gitk show the delta queues in the right order. -=item Show complete diff since the last upload: +=back + +Complete diff since the last upload: + +=over % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches (Includes changes to upstream files.) -=item Interdiff of delta queue since last upload, if you really want that: +=back + +Interdiff of delta queue since last upload, if you really want it: % git debrebase make-patches % git diff dgit/dgit/sid..HEAD -- debian/patches -=back - Also of course there is % git debrebase status -- 2.11.0
From d4bc39ef9b3e33312eeeeb339a411391d40aa075 Mon Sep 17 00:00:00 2001 From: Sean Whitton <[email protected]> Date: Sun, 26 Aug 2018 09:24:49 -0700 Subject: [PATCH 3/3] dgit-maint-debrebase(7): Formatting & wording tweaks Signed-off-by: Sean Whitton <[email protected]> --- dgit-maint-debrebase.7.pod | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/dgit-maint-debrebase.7.pod b/dgit-maint-debrebase.7.pod index cc393b5..e5abe17 100644 --- a/dgit-maint-debrebase.7.pod +++ b/dgit-maint-debrebase.7.pod @@ -627,7 +627,7 @@ package, but this should already be represented in your git history.) The git history made by git-debrebase can seem complicated. Here are some suggestions for helpful invocations of gitk and git. -They can be adapted for other tools like tig, git log, etc. +They can be adapted for other tools like tig(1), git-log(1), magit, etc. History of package in Debian, disregarding history from upstream: @@ -665,7 +665,8 @@ Complete diff since the last upload: =over % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches -(Includes changes to upstream files.) + +This includes changes to upstream files. =back @@ -674,7 +675,7 @@ Interdiff of delta queue since last upload, if you really want it: % git debrebase make-patches % git diff dgit/dgit/sid..HEAD -- debian/patches -Also of course there is +And of course there is: % git debrebase status -- 2.11.0
signature.asc
Description: PGP signature
