{"thread":{"id":"64208","subject":"[RFC PATCH 2/4] doc: remembering-renames.adoc: fix asciidoc warnings","startedAt":"2025-09-26T00:24:25Z","lastAt":"2025-09-26T15:42:42Z","messageCount":2,"participants":["Ramsay Jones","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"527383","messageId":"6dc8844c-8554-4c6c-a3bd-5ad2c04ab7a6@ramsayjones.plus.com","threadId":"64208","inReplyTo":null,"subject":"[RFC PATCH 2/4] doc: remembering-renames.adoc: fix asciidoc warnings","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T00:24:22Z","receivedAt":"2025-09-26T00:24:25Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\nSigned-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>\n---\n .../technical/remembering-renames.adoc        | 63 +++++++++----------\n 1 file changed, 31 insertions(+), 32 deletions(-)\n\ndiff --git a/Documentation/technical/remembering-renames.adoc b/Documentation/technical/remembering-renames.adoc\nindex 73f41761e2..89db8b406d 100644\n--- a/Documentation/technical/remembering-renames.adoc\n+++ b/Documentation/technical/remembering-renames.adoc\n@@ -10,32 +10,32 @@ history as an optimization, assuming all merges are automatic and clean\n \n Outline:\n \n-  0. Assumptions\n+  0 Assumptions\n \n-  1. How rebasing and cherry-picking work\n+  1 How rebasing and cherry-picking work\n \n-  2. Why the renames on MERGE_SIDE1 in any given pick are *always* a\n-     superset of the renames on MERGE_SIDE1 for the next pick.\n+  2 Why the renames on MERGE_SIDE1 in any given pick are *always* a\n+    superset of the renames on MERGE_SIDE1 for the next pick.\n \n-  3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also\n-     a rename on MERGE_SIDE1 for the next pick\n+  3 Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also\n+    a rename on MERGE_SIDE1 for the next pick\n \n-  4. A detailed description of the counter-examples to #3.\n+  4 A detailed description of the counter-examples to #3.\n \n-  5. Why the special cases in #4 are still fully reasonable to use to pair\n-     up files for three-way content merging in the merge machinery, and why\n-     they do not affect the correctness of the merge.\n+  5 Why the special cases in #4 are still fully reasonable to use to pair\n+    up files for three-way content merging in the merge machinery, and why\n+    they do not affect the correctness of the merge.\n \n-  6. Interaction with skipping of \"irrelevant\" renames\n+  6 Interaction with skipping of \"irrelevant\" renames\n \n-  7. Additional items that need to be cached\n+  7 Additional items that need to be cached\n \n-  8. How directory rename detection interacts with the above and why this\n-     optimization is still safe even if merge.directoryRenames is set to\n-     \"true\".\n+  8 How directory rename detection interacts with the above and why this\n+    optimization is still safe even if merge.directoryRenames is set to\n+    \"true\".\n \n \n-=== 0. Assumptions ===\n+== 0. Assumptions ==\n \n There are two assumptions that will hold throughout this document:\n \n@@ -91,7 +91,7 @@ this config setting, but we have to discuss a few more cases to show why;\n this discussion is deferred until section 8.\n \n \n-=== 1. How rebasing and cherry-picking work ===\n+== 1. How rebasing and cherry-picking work ==\n \n Consider the following setup (from the git-rebase manpage):\n \n@@ -138,8 +138,7 @@ Conceptually the two statements above are the same as a three-way merge of\n B, B', and C, at least the parts before you decide to record a commit.\n \n \n-=== 2. Why the renames on MERGE_SIDE1 in any given pick are always a ===\n-===    superset of the renames on MERGE_SIDE1 for the next pick.     ===\n+== 2. Why the renames on MERGE_SIDE1 in any given pick are always a superset of the renames on MERGE_SIDE1 for the next pick. ==\n \n The merge machinery uses the filenames it is fed from MERGE_BASE,\n MERGE_SIDE1, and MERGE_SIDE2.  It will only move content to a different\n@@ -181,8 +180,7 @@ are a subset of those between E and G.  Equivalently, all renames between E\n and G are a superset of those between A and A'.\n \n \n-=== 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_   ===\n-===    always also a rename on MERGE_SIDE1 for the next pick.        ===\n+== 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also a rename on MERGE_SIDE1 for the next pick. ==\n \n Let's again look at the first two picks:\n \n@@ -254,7 +252,7 @@ were detected as renames, A:oldfile and A':newfile should also be\n detectable as renames almost always.\n \n \n-=== 4. A detailed description of the counter-examples to #3.         ===\n+== 4. A detailed description of the counter-examples to #3. ==\n \n We already noted in section 3 that rename/rename(1to1) (i.e. both sides\n renaming a file the same way) was one counter-example.  The more\n@@ -276,18 +274,21 @@ still somehow merge cleanly), then traditional rename detection would not\n detect A:oldfile and A':newfile as renames.\n \n Here's an example where that can happen:\n+\n   * E:oldfile had 20 lines\n+\n   * G:newfile added 10 new lines at the beginning of the file\n+\n   * A:oldfile kept the first 3 lines of the file, and deleted all the rest\n+\n then\n+\n   => A':newfile would have 13 lines, 3 of which matches those in A:oldfile.\n-E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and\n-A':newfile would not be.\n+  E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and\n+  A':newfile would not be.\n \n \n-=== 5. Why the special cases in #4 are still fully reasonable to use to    ===\n-===    pair up files for three-way content merging in the merge machinery, ===\n-===    and why they do not affect the correctness of the merge.            ===\n+== 5. Why the special cases in #4 are still fully reasonable to use to pair up files for three-way content merging in the merge machinery, and why they do not affect the correctness of the merge. ==\n \n In the rename/rename(1to1) case, A:newfile and A':newfile are not renames\n since they use the *same* filename.  However, files with the same filename\n@@ -394,7 +395,7 @@ cases 1 and 3 seem to provide as good or better behavior with the\n optimization than without.\n \n \n-=== 6. Interaction with skipping of \"irrelevant\" renames ===\n+== 6. Interaction with skipping of \"irrelevant\" renames ==\n \n Previous optimizations involved skipping rename detection for paths\n considered to be \"irrelevant\".  See for example the following commits:\n@@ -421,7 +422,7 @@ detection -- though we can limit it to the paths for which we have not\n already detected renames.\n \n \n-=== 7. Additional items that need to be cached ===\n+== 7. Additional items that need to be cached ==\n \n It turns out we have to cache more than just renames; we also cache:\n \n@@ -482,9 +483,7 @@ we store the trees to compare with what we are asked to merge next\n time.\n \n \n-=== 8. How directory rename detection interacts with the above and   ===\n-===    why this optimization is still safe even if                   ===\n-===    merge.directoryRenames is set to \"true\".                      ===\n+== 8. How directory rename detection interacts with the above and why this optimization is still safe even if merge.directoryRenames is set to \"true\". ==\n \n As noted in the assumptions section:\n \n-- \n2.51.0\n"},{"id":"527428","messageId":"xmqqqzvtcj9s.fsf@gitster.g","threadId":"64208","inReplyTo":"6dc8844c-8554-4c6c-a3bd-5ad2c04ab7a6@ramsayjones.plus.com","subject":"Re: [RFC PATCH 2/4] doc: remembering-renames.adoc: fix asciidoc warnings","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-26T15:42:39Z","receivedAt":"2025-09-26T15:42:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones <ramsay@ramsayjones.plus.com> writes:\n\n> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>\n> ---\n>  .../technical/remembering-renames.adoc        | 63 +++++++++----------\n>  1 file changed, 31 insertions(+), 32 deletions(-)\n\nI know this is RFC not to be directly applied yet, but can you\ndescribe what warnings are in scope of this fix to help commenting\non the changes?\n\n> diff --git a/Documentation/technical/remembering-renames.adoc b/Documentation/technical/remembering-renames.adoc\n> index 73f41761e2..89db8b406d 100644\n> --- a/Documentation/technical/remembering-renames.adoc\n> +++ b/Documentation/technical/remembering-renames.adoc\n> @@ -10,32 +10,32 @@ history as an optimization, assuming all merges are automatic and clean\n>  \n>  Outline:\n>  \n> -  0. Assumptions\n> +  0 Assumptions\n>  \n> -  1. How rebasing and cherry-picking work\n> +  1 How rebasing and cherry-picking work\n> ...  \n> -  8. How directory rename detection interacts with the above and why this\n> -     optimization is still safe even if merge.directoryRenames is set to\n> -     \"true\".\n> +  8 How directory rename detection interacts with the above and why this\n> +    optimization is still safe even if merge.directoryRenames is set to\n> +    \"true\".\n\nI always thought that numbered list would have a period \".\" after\nthe number, but if doing this produces commonly accepted rendition\nof a numbered list without warnings, I can buy it.  I personally may\nfeel it a bit awkward to read the source text until I get\naccustomed, though.\n\n> -=== 0. Assumptions ===\n> +== 0. Assumptions ==\n\nThis is because these sections are not nested within a group that is\nheaded with a \"== title ==\" chapter?  Which makes sense.  I notice\nthat this one has a period \".\" after the number (which the warning\nmechanism probably did not care---it is just part of the title).\n\n>  Here's an example where that can happen:\n> +\n>    * E:oldfile had 20 lines\n> +\n>    * G:newfile added 10 new lines at the beginning of the file\n> +\n>    * A:oldfile kept the first 3 lines of the file, and deleted all the rest\n> +\n>  then\n> +\n>    => A':newfile would have 13 lines, 3 of which matches those in A:oldfile.\n> -E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and\n> -A':newfile would not be.\n> +  E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and\n> +  A':newfile would not be.\n\nWith blank lines in between I personally find the source text easier\nto read, so no complaints ;-)\n"}]}