| Message ID | f26b53e3-e7d1-f0fe-cdd3-dd734beb1628@kdbg.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | rebase docs: fix incorrect format of the section Behavioral Differences | expand |
On Mon, 3 Dec 2018 at 18:35, Johannes Sixt <j6t@kdbg.org> wrote: > I actually did not test the result, because I don't have the > infrastructure. I've tested with asciidoc and Asciidoctor, html and man-page. Looks good. Martin
Am 03.12.18 um 21:42 schrieb Martin Ågren: > On Mon, 3 Dec 2018 at 18:35, Johannes Sixt <j6t@kdbg.org> wrote: >> I actually did not test the result, because I don't have the >> infrastructure. > > I've tested with asciidoc and Asciidoctor, html and man-page. Looks > good. Thank you so much! -- Hannes
Hi Hannes, On Mon, 3 Dec 2018, Johannes Sixt wrote: > The text body of section Behavioral Differences is typeset as code, > but should be regular text. Remove the indentation to achieve that. > > While here, prettify the language: > > - use "the x backend" instead of "x-based rebase"; > - use present tense instead of future tense; > > and use subsections instead of a list. > > Signed-off-by: Johannes Sixt <j6t@kdbg.org> > --- The changes look sensible to me. Thanks, Dscho > Cf. https://git-scm.com/docs/git-rebase#_behavioral_differences > > I actually did not test the result, because I don't have the > infrastructure. > > The sentence "The am backend sometimes does not" is not very useful, > but is not my fault ;) It would be great if it could be made more > specific, but I do not know the details. > > Documentation/git-rebase.txt | 30 +++++++++++++++++------------- > 1 file changed, 17 insertions(+), 13 deletions(-) > > diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt > index 80793bad8d..dff17b3178 100644 > --- a/Documentation/git-rebase.txt > +++ b/Documentation/git-rebase.txt > @@ -550,24 +550,28 @@ Other incompatible flag pairs: > BEHAVIORAL DIFFERENCES > ----------------------- > > - * empty commits: > +There are some subtle differences how the backends behave. > > - am-based rebase will drop any "empty" commits, whether the > - commit started empty (had no changes relative to its parent to > - start with) or ended empty (all changes were already applied > - upstream in other commits). > +Empty commits > +~~~~~~~~~~~~~ > + > +The am backend drops any "empty" commits, regardless of whether the > +commit started empty (had no changes relative to its parent to > +start with) or ended empty (all changes were already applied > +upstream in other commits). > > - merge-based rebase does the same. > +The merge backend does the same. > > - interactive-based rebase will by default drop commits that > - started empty and halt if it hits a commit that ended up empty. > - The `--keep-empty` option exists for interactive rebases to allow > - it to keep commits that started empty. > +The interactive backend drops commits by default that > +started empty and halts if it hits a commit that ended up empty. > +The `--keep-empty` option exists for the interactive backend to allow > +it to keep commits that started empty. > > - * directory rename detection: > +Directory rename detection > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > > - merge-based and interactive-based rebases work fine with > - directory rename detection. am-based rebases sometimes do not. > +The merge and interactive backends work fine with > +directory rename detection. The am backend sometimes does not. > > include::merge-strategies.txt[] > > -- > 2.19.1.1133.g2dd3d172d2 >
Johannes Sixt <j6t@kdbg.org> writes: > Am 03.12.18 um 21:42 schrieb Martin Ågren: >> On Mon, 3 Dec 2018 at 18:35, Johannes Sixt <j6t@kdbg.org> wrote: >>> I actually did not test the result, because I don't have the >>> infrastructure. >> >> I've tested with asciidoc and Asciidoctor, html and man-page. Looks >> good. > > Thank you so much! > > -- Hannes Thanks, both.
On Mon, 3 Dec 2018, Johannes Sixt wrote: > The text body of section Behavioral Differences is typeset as code, > but should be regular text. Remove the indentation to achieve that. > > While here, prettify the language: > > - use "the x backend" instead of "x-based rebase"; > - use present tense instead of future tense; > > and use subsections instead of a list. > > Signed-off-by: Johannes Sixt <j6t@kdbg.org> > --- > Cf. https://git-scm.com/docs/git-rebase#_behavioral_differences > > I actually did not test the result, because I don't have the > infrastructure. > > The sentence "The am backend sometimes does not" is not very useful, > but is not my fault ;) It would be great if it could be made more > specific, but I do not know the details. That sentence is my fault. I've been sitting on a patch for about a week that fixes it which I was going to submit after 2.20.0, but since you're fixing this text up right now, I guess putting these two patches together makes sense. I've rebased it on top of your commit and provided it below. -- 8< -- Subject: [PATCH] git-rebase.txt: update note about directory rename detection and am In commit 6aba117d5cf7 ("am: avoid directory rename detection when calling recursive merge machinery", 2018-08-29), the git-rebase manpage probably should have also been updated to note the stronger incompatibility between git-am and directory rename detection. Update it now. Signed-off-by: Elijah Newren <newren@gmail.com> --- Documentation/git-rebase.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 41631df6e4..b220b8b2b6 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -569,8 +569,12 @@ it to keep commits that started empty. Directory rename detection ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The merge and interactive backends work fine with -directory rename detection. The am backend sometimes does not. +The merge and interactive backends work fine with directory rename +detection. The am backend sometimes does not because it operates on +"fake ancestors" that involve trees containing only the files modified +in the patch. Without accurate tree information, directory rename +detection cannot safely operate and is thus turned off in the am +backend. include::merge-strategies.txt[]
Am 04.12.18 um 22:24 schrieb Elijah Newren: > +.... The am backend sometimes does not because it operates on > +"fake ancestors" that involve trees containing only the files modified > +in the patch. Without accurate tree information, directory rename > +detection cannot safely operate and is thus turned off in the am > +backend. Directory rename detection does not work sometimes. That is, it works most of the time. But how can that be the case when it is turned off? -- Hannes
On Tue, Dec 4, 2018 at 1:53 PM Johannes Sixt <j6t@kdbg.org> wrote: > > Am 04.12.18 um 22:24 schrieb Elijah Newren: > > +.... The am backend sometimes does not because it operates on > > +"fake ancestors" that involve trees containing only the files modified > > +in the patch. Without accurate tree information, directory rename > > +detection cannot safely operate and is thus turned off in the am > > +backend. > > Directory rename detection does not work sometimes. That is, it works > most of the time. But how can that be the case when it is turned off? Gah, when I was rebasing on your patch I adopted your sentence rewrite but forgot to remove the "sometimes". Thanks for catching; correction: -- 8< -- Subject: [PATCH v2] git-rebase.txt: update note about directory rename detection and am In commit 6aba117d5cf7 ("am: avoid directory rename detection when calling recursive merge machinery", 2018-08-29), the git-rebase manpage probably should have also been updated to note the stronger incompatibility between git-am and directory rename detection. Update it now. Signed-off-by: Elijah Newren <newren@gmail.com> --- Documentation/git-rebase.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 41631df6e4..ef76cccf3f 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -569,8 +569,12 @@ it to keep commits that started empty. Directory rename detection ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The merge and interactive backends work fine with -directory rename detection. The am backend sometimes does not. +The merge and interactive backends work fine with directory rename +detection. The am backend does not because it operates on "fake +ancestors" that involve trees containing only the files modified in +the patch. Without accurate tree information, directory rename +detection cannot safely operate and is thus turned off in the am +backend. include::merge-strategies.txt[]
Elijah Newren <newren@gmail.com> writes: > Gah, when I was rebasing on your patch I adopted your sentence rewrite > but forgot to remove the "sometimes". Thanks for catching; correction: > > -- 8< -- > Subject: [PATCH v2] git-rebase.txt: update note about directory rename > detection and am > > In commit 6aba117d5cf7 ("am: avoid directory rename detection when > calling recursive merge machinery", 2018-08-29), the git-rebase manpage > probably should have also been updated to note the stronger > incompatibility between git-am and directory rename detection. Update > it now. > > Signed-off-by: Elijah Newren <newren@gmail.com> > --- > Documentation/git-rebase.txt | 8 ++++++-- > 1 file changed, 6 insertions(+), 2 deletions(-) > > diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt > index 41631df6e4..ef76cccf3f 100644 > --- a/Documentation/git-rebase.txt > +++ b/Documentation/git-rebase.txt > @@ -569,8 +569,12 @@ it to keep commits that started empty. > Directory rename detection > ~~~~~~~~~~~~~~~~~~~~~~~~~~ > > -The merge and interactive backends work fine with > -directory rename detection. The am backend sometimes does not. > +The merge and interactive backends work fine with directory rename I am not sure "work fine" a fair and correct label, as rename is always heuristic. The "directory rename detection" heuristic in "merge" and the "interactive" backends can take what happened to paths in the same directory into account when deciding if a disappeared path was "renamed" and to which other path. The heuristic produces incorrect result when the information given is only about changed paths, which is why it is disabled when using the "am" backend. perhaps.
On Tue, Dec 4, 2018 at 7:54 PM Junio C Hamano <gitster@pobox.com> wrote: > > Elijah Newren <newren@gmail.com> writes: > > > Gah, when I was rebasing on your patch I adopted your sentence rewrite > > but forgot to remove the "sometimes". Thanks for catching; correction: > > > > > -- 8< -- > > Subject: [PATCH v2] git-rebase.txt: update note about directory rename > > detection and am > > > > In commit 6aba117d5cf7 ("am: avoid directory rename detection when > > calling recursive merge machinery", 2018-08-29), the git-rebase manpage > > probably should have also been updated to note the stronger > > incompatibility between git-am and directory rename detection. Update > > it now. > > > > Signed-off-by: Elijah Newren <newren@gmail.com> > > --- > > Documentation/git-rebase.txt | 8 ++++++-- > > 1 file changed, 6 insertions(+), 2 deletions(-) > > > > diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt > > index 41631df6e4..ef76cccf3f 100644 > > --- a/Documentation/git-rebase.txt > > +++ b/Documentation/git-rebase.txt > > @@ -569,8 +569,12 @@ it to keep commits that started empty. > > Directory rename detection > > ~~~~~~~~~~~~~~~~~~~~~~~~~~ > > > > -The merge and interactive backends work fine with > > -directory rename detection. The am backend sometimes does not. > > +The merge and interactive backends work fine with directory rename > > I am not sure "work fine" a fair and correct label, as rename is > always heuristic. > > The "directory rename detection" heuristic in "merge" and the > "interactive" backends can take what happened to paths in the > same directory into account when deciding if a disappeared path > was "renamed" and to which other path. The heuristic produces > incorrect result when the information given is only about > changed paths, which is why it is disabled when using the "am" > backend. > > perhaps. The general idea sounds good. Does adding a few more details help with understanding, or is it more of an information overload? I'm thinking of something like: The "directory rename detection" heuristic in the "merge" and "interactive" backends can take what happened to paths in the same directory on the other side of history into account when deciding whether a new path in that directory should instead be moved elsewhere. The heuristic produces incorrect results when the only information available is about files which were changed on the side of history being rebased, which is why directory rename detection is disabled when using the "am" backend.
Am 05.12.18 um 07:20 schrieb Elijah Newren: > On Tue, Dec 4, 2018 at 7:54 PM Junio C Hamano <gitster@pobox.com> wrote: >> >> Elijah Newren <newren@gmail.com> writes: >> >>> Gah, when I was rebasing on your patch I adopted your sentence rewrite >>> but forgot to remove the "sometimes". Thanks for catching; correction: >> >>> >>> -- 8< -- >>> Subject: [PATCH v2] git-rebase.txt: update note about directory rename >>> detection and am >>> >>> In commit 6aba117d5cf7 ("am: avoid directory rename detection when >>> calling recursive merge machinery", 2018-08-29), the git-rebase manpage >>> probably should have also been updated to note the stronger >>> incompatibility between git-am and directory rename detection. Update >>> it now. >>> >>> Signed-off-by: Elijah Newren <newren@gmail.com> >>> --- >>> Documentation/git-rebase.txt | 8 ++++++-- >>> 1 file changed, 6 insertions(+), 2 deletions(-) >>> >>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt >>> index 41631df6e4..ef76cccf3f 100644 >>> --- a/Documentation/git-rebase.txt >>> +++ b/Documentation/git-rebase.txt >>> @@ -569,8 +569,12 @@ it to keep commits that started empty. >>> Directory rename detection >>> ~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> >>> -The merge and interactive backends work fine with >>> -directory rename detection. The am backend sometimes does not. >>> +The merge and interactive backends work fine with directory rename >> >> I am not sure "work fine" a fair and correct label, as rename is >> always heuristic. >> >> The "directory rename detection" heuristic in "merge" and the >> "interactive" backends can take what happened to paths in the >> same directory into account when deciding if a disappeared path >> was "renamed" and to which other path. The heuristic produces >> incorrect result when the information given is only about >> changed paths, which is why it is disabled when using the "am" >> backend. >> >> perhaps. > > The general idea sounds good. Does adding a few more details help > with understanding, or is it more of an information overload? I'm > thinking of something like: > > The "directory rename detection" heuristic in the "merge" and > "interactive" backends can take what happened to paths in the > same directory on the other side of history into account when > deciding whether a new path in that directory should instead be > moved elsewhere. The heuristic produces incorrect results when > the only information available is about files which were changed > on the side of history being rebased, which is why directory > rename detection is disabled when using the "am" backend. Please let me deposit my objection. This paragraph is not the right place to explain what directory renme detection is and how it works under the hood. "works fine" in the original text is the right phrase here; if there is concern that this induces expectations that cannot be met, throw in the word "heuristics". Such as: Directory rename heuristics work fine in the merge and interactive backends. It does not in the am backend because... -- Hannes
Johannes Sixt <j6t@kdbg.org> writes: > Please let me deposit my objection. This paragraph is not the right > place to explain what directory renme detection is and how it works > under the hood. "works fine" in the original text is the right phrase > here; if there is concern that this induces expectations that cannot > be met, throw in the word "heuristics". > > Such as: > Directory rename heuristics work fine in the merge and interactive > backends. It does not in the am backend because... OK, good enough, I guess. Or just s/work fine/is enabled/.
On Tue, Dec 4, 2018 at 11:40 PM Junio C Hamano <gitster@pobox.com> wrote: > > Johannes Sixt <j6t@kdbg.org> writes: > > > Please let me deposit my objection. This paragraph is not the right > > place to explain what directory renme detection is and how it works > > under the hood. "works fine" in the original text is the right phrase > > here; if there is concern that this induces expectations that cannot > > be met, throw in the word "heuristics". > > > > Such as: > > Directory rename heuristics work fine in the merge and interactive > > backends. It does not in the am backend because... > > OK, good enough, I guess. Or just s/work fine/is enabled/. So... Directory rename heuristics are enabled in the merge and interactive backends. They are not in the am backend because it operates on "fake ancestors" that involve trees containing only the files modified in the patch. Due to the lack of accurate tree information, directory rename detection is disabled for the am backend. ?
Am 05.12.18 um 16:37 schrieb Elijah Newren: > On Tue, Dec 4, 2018 at 11:40 PM Junio C Hamano <gitster@pobox.com> wrote: >> >> Johannes Sixt <j6t@kdbg.org> writes: >> >>> Please let me deposit my objection. This paragraph is not the right >>> place to explain what directory renme detection is and how it works >>> under the hood. "works fine" in the original text is the right phrase >>> here; if there is concern that this induces expectations that cannot >>> be met, throw in the word "heuristics". >>> >>> Such as: >>> Directory rename heuristics work fine in the merge and interactive >>> backends. It does not in the am backend because... >> >> OK, good enough, I guess. Or just s/work fine/is enabled/. > > So... > > Directory rename heuristics are enabled in the merge and interactive > backends. They are not in the am backend because it operates on > "fake ancestors" that involve trees containing only the files modified > in the patch. Due to the lack of accurate tree information, directory > rename detection is disabled for the am backend. OK with me. And also if you drop sentence no.2 and keep just no.1 and no.3. Thanks, -- Hannes
Johannes Sixt <j6t@kdbg.org> writes: > Am 05.12.18 um 16:37 schrieb Elijah Newren: >> On Tue, Dec 4, 2018 at 11:40 PM Junio C Hamano <gitster@pobox.com> wrote: >>> >>> Johannes Sixt <j6t@kdbg.org> writes: >>> >>>> Please let me deposit my objection. This paragraph is not the right >>>> place to explain what directory renme detection is and how it works >>>> under the hood. "works fine" in the original text is the right phrase >>>> here; if there is concern that this induces expectations that cannot >>>> be met, throw in the word "heuristics". >>>> >>>> Such as: >>>> Directory rename heuristics work fine in the merge and interactive >>>> backends. It does not in the am backend because... >>> >>> OK, good enough, I guess. Or just s/work fine/is enabled/. >> >> So... >> >> Directory rename heuristics are enabled in the merge and interactive >> backends. They are not in the am backend because it operates on >> "fake ancestors" that involve trees containing only the files modified >> in the patch. Due to the lack of accurate tree information, directory >> rename detection is disabled for the am backend. > > OK with me. And also if you drop sentence no.2 and keep just no.1 and no.3. Yeah, that shorter version may be sufficient to explain why we do not use the heuristics in the "am" backend.
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 80793bad8d..dff17b3178 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -550,24 +550,28 @@ Other incompatible flag pairs: BEHAVIORAL DIFFERENCES ----------------------- - * empty commits: +There are some subtle differences how the backends behave. - am-based rebase will drop any "empty" commits, whether the - commit started empty (had no changes relative to its parent to - start with) or ended empty (all changes were already applied - upstream in other commits). +Empty commits +~~~~~~~~~~~~~ + +The am backend drops any "empty" commits, regardless of whether the +commit started empty (had no changes relative to its parent to +start with) or ended empty (all changes were already applied +upstream in other commits). - merge-based rebase does the same. +The merge backend does the same. - interactive-based rebase will by default drop commits that - started empty and halt if it hits a commit that ended up empty. - The `--keep-empty` option exists for interactive rebases to allow - it to keep commits that started empty. +The interactive backend drops commits by default that +started empty and halts if it hits a commit that ended up empty. +The `--keep-empty` option exists for the interactive backend to allow +it to keep commits that started empty. - * directory rename detection: +Directory rename detection +~~~~~~~~~~~~~~~~~~~~~~~~~~ - merge-based and interactive-based rebases work fine with - directory rename detection. am-based rebases sometimes do not. +The merge and interactive backends work fine with +directory rename detection. The am backend sometimes does not. include::merge-strategies.txt[]
The text body of section Behavioral Differences is typeset as code, but should be regular text. Remove the indentation to achieve that. While here, prettify the language: - use "the x backend" instead of "x-based rebase"; - use present tense instead of future tense; and use subsections instead of a list. Signed-off-by: Johannes Sixt <j6t@kdbg.org> --- Cf. https://git-scm.com/docs/git-rebase#_behavioral_differences I actually did not test the result, because I don't have the infrastructure. The sentence "The am backend sometimes does not" is not very useful, but is not my fault ;) It would be great if it could be made more specific, but I do not know the details. Documentation/git-rebase.txt | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-)