{"thread":{"id":"58125","subject":"[PATCH 0/4] Add some Glossary terms, and extra renormalize information.","startedAt":"2022-07-09T16:56:28Z","lastAt":"2022-10-29T17:34:52Z","messageCount":45,"participants":["Philip Oakley via GitGitGadget","Junio C Hamano","Torsten Bögershausen","Philip Oakley","Abhradeep Chakraborty","Derrick Stolee","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"458688","messageId":"pull.1282.git.1657385781.gitgitgadget@gmail.com","threadId":"58125","inReplyTo":null,"subject":"[PATCH 0/4] Add some Glossary terms, and extra renormalize information.","fromName":"Philip Oakley via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-07-09T16:56:17Z","receivedAt":"2022-07-09T16:56:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This short series looks to add the basics of the reachability bitmap and\ncommit graph phrases to the glossary of terms. While these techniques are\nwell known to their developers, for some, they are just magic phrases.\n\nThe first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]\n\nPatch [2/4] provides a basic statement for the Commit-Graph's purpose.\n\nPatch [3/4] provides a similar statement for the reachability bitmaps.\n\nThese two patches maybe misses out on some linking information as to the\nbenefits these have and the basics of their heuristic.\n\nPatch [4/4] follows up on a bug report about the lack of idempotence for the\n`--renormalise' command. See commit message for details.\n\n[0] UNA Un-Named Abbreviation.\n\nSigned-off-by: Philip Oakley philipoakley@iee.email\n\nPhilip Oakley (4):\n glossary: add Object DataBase (ODB) abbreviation\n glossary: add commit graph description\n glossary: add reachability bitmap description\n doc add: renormalize is not idempotent for CRCRLF\n\n Documentation/git-add.txt | 3 ++-\n Documentation/glossary-content.txt | 15 ++++++++++++++-\n 2 files changed, 16 insertions(+), 2 deletions(-)\n\n\nbase-commit: 30cc8d0f147546d4dd77bf497f4dec51e7265bd8\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1282%2FPhilipOakley%2FGlossary_terms-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1282/PhilipOakley/Glossary_terms-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1282\n-- \ngitgitgadget\n"},{"id":"458689","messageId":"f4c04019edcc3f81aa0bf877f9138c2dd7da9f05.1657385781.git.gitgitgadget@gmail.com","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"[PATCH 1/4] glossary: add Object DataBase (ODB) abbreviation","fromName":"Philip Oakley via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-07-09T16:56:18Z","receivedAt":"2022-07-09T16:56:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: Philip Oakley \n\nODB abbreviation is used in the technical section without expansion.\nShow the abbreviation in the Glossary.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex aa2f41f5e70..f3342a5ab69 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -257,7 +257,7 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \t<> of its contents. Consequently, an\n \tobject cannot be changed.\n \n-[[def_object_database]]object database::\n+[[def_object_database]]object database (ODB)::\n \tStores a set of \"objects\", and an individual <> is\n \tidentified by its <>. The objects usually\n \tlive in `$GIT_DIR/objects/`.\n-- \ngitgitgadget\n\n"},{"id":"458690","messageId":"32777cae24de91b0fb873ea04a802630ab85aafe.1657385781.git.gitgitgadget@gmail.com","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"[PATCH 2/4] glossary: add commit graph description","fromName":"Philip Oakley via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-07-09T16:56:19Z","receivedAt":"2022-07-09T16:56:31Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: Philip Oakley \n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex f3342a5ab69..a9e69949a4e 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -75,6 +75,13 @@ state in the Git history, by creating a new commit representing the current\n state of the <> and advancing <>\n to point at the new commit.\n \n+[[def_commit_graph]]commit graph::\n+\tThe commit-graph file is a supplemental data structure that\n+\taccelerates commit graph walks. The existing Object Data Base (ODB)\n+\tis the definitive commit graph. The \"commit-graph\" file is stored\n+\teither in the .git/objects/info directory or in the info directory\n+\tof an alternate object database.\n+\n [[def_commit_object]]commit object::\n \tAn <> which contains the information about a\n \tparticular <>, such as <>, committer,\n-- \ngitgitgadget\n\n"},{"id":"458691","messageId":"63d3026adf8c490dc205fcec0e2d87b3ce74200e.1657385781.git.gitgitgadget@gmail.com","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"[PATCH 3/4] glossary: add reachability bitmap description","fromName":"Philip Oakley via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-07-09T16:56:20Z","receivedAt":"2022-07-09T16:56:34Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: Philip Oakley \n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex a9e69949a4e..6302df90563 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -500,6 +500,12 @@ exclude;;\n \t<> to the trees or <>\n \tthat they contain.\n \n+[[def_reachability_bitmap]]reachability bitmaps::\n+\tReachability bitmaps store information about the set of objects in\n+\ta packfile, or a multi-pack index (MIDX). A repository may have at\n+\tmost one bitmap. The bitmap may belong to either one pack, or the\n+\trepository's multi-pack index (if it exists).\n+\n [[def_rebase]]rebase::\n \tTo reapply a series of changes from a <> to a\n \tdifferent base, and reset the <> of that branch\n-- \ngitgitgadget\n\n"},{"id":"458692","messageId":"d3b8ed97a105ea1d7e656c964b7eee378e11ede6.1657385781.git.gitgitgadget@gmail.com","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"[PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-07-09T16:56:21Z","receivedAt":"2022-07-09T16:56:43Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: Philip Oakley \n\nBug report\n https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\nnoted that a file containing /r/r/n needed renormalising twice.\n\nThis is by design. Lone CR characters, not paired with an LF, are left\nunchanged. Note the lack of idempotentness of the \"clean\" filter in the\ndocumentation.\n\nRenormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\nTorsten Bögershausen, 2017-11-16)\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-add.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 11eb70f16c7..c4a5ad11a6b 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -188,7 +188,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n \tforcibly add them again to the index. This is useful after\n \tchanging `core.autocrlf` configuration or the `text` attribute\n \tin order to correct files added with wrong CRLF/LF line endings.\n-\tThis option implies `-u`.\n+\tThis option implies `-u`. Lone CR characters are untouched, so\n+\tcleaning not idempotent. A CRCRLF sequence cleans to CRLF.\n \n --chmod=(+|-)x::\n \tOverride the executable bit of the added files. The executable\n-- \ngitgitgadget\n"},{"id":"458695","messageId":"xmqqilo6t2qy.fsf@gitster.g","threadId":"58125","inReplyTo":"d3b8ed97a105ea1d7e656c964b7eee378e11ede6.1657385781.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-09T21:06:29Z","receivedAt":"2022-07-09T21:16:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley via GitGitGadget\" writes:\n\n> From: Philip Oakley \n>\n> Bug report\n> https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\n> noted that a file containing /r/r/n needed renormalising twice.\n\nDid you mean backslash, not forward?\n\n> This is by design. Lone CR characters, not paired with an LF, are left\n> unchanged. Note the lack of idempotentness of the \"clean\" filter in the\n> documentation.\n\nOK.\n\n\n> Renormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\n> Torsten Bögershausen, 2017-11-16)\n\nDoes this need to be said \"HERE\", rather than leaving it to run \"git\nblame\" for those who became curious?\n\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/git-add.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index 11eb70f16c7..c4a5ad11a6b 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -188,7 +188,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n> \tforcibly add them again to the index. This is useful after\n> \tchanging `core.autocrlf` configuration or the `text` attribute\n> \tin order to correct files added with wrong CRLF/LF line endings.\n> -\tThis option implies `-u`.\n> +\tThis option implies `-u`. Lone CR characters are untouched, so\n> +\tcleaning not idempotent. A CRCRLF sequence cleans to CRLF.\n\nLack of verb BE somewhere.\n\nDo we expect our readers all understand the math-y word? It is not\ntoo hard to explain it to math-uninitiated, e.g.\n\n This option implies `-u`. Note that running renormalize again\n on the result of running renormalize may make it even \"more\n normal\". A CR-CR-LF sequence would first renormalize to CR-LF\n (the first CR, a lone CR, is left intact, and CR-LF that follows\n normalizes to LF). If you run renormalize again, the resulting\n CR-LF will normalize down to LF.\n\n"},{"id":"458696","messageId":"xmqqedyut22w.fsf@gitster.g","threadId":"58125","inReplyTo":"32777cae24de91b0fb873ea04a802630ab85aafe.1657385781.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] glossary: add commit graph description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-09T21:20:55Z","receivedAt":"2022-07-09T21:21:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley via GitGitGadget\" writes:\n\n> +[[def_commit_graph]]commit graph::\n> +\tThe commit-graph file is a supplemental data structure that\n> +\taccelerates commit graph walks. The existing Object Data Base (ODB)\n> +\tis the definitive commit graph. The \"commit-graph\" file is stored\n> +\teither in the .git/objects/info directory or in the info directory\n> +\tof an alternate object database.\n\nWhile it says nothing technically incorrect, I suspect \"The existing\nobject data base is the definitive commit graph\" may invite unneeded\nconfusion.\n\nI think you wanted to say that the DAG formed by traversing the\npointers recorded in the objects is the authoritative source of\ntruth and the commit-graph file is merely a precomputed cache and\ncan be safely lost, but I am not sure the above description conveys\nthat to anybody who does not already know it.\n\n The commits in the object data base form a directed acyclic\n graph (DAG) by commits referring to their parent commits.\n Pieces of information from individual commit objects that are\n needed to traverse the DAG are pre-computed in the commit-graph\n file and stored in ...\n\nis my attempt---I am not very happy or proud about it, but it may be\neasier to follow.\n\nThanks.\n\n\n"},{"id":"458697","messageId":"xmqqa69it1g9.fsf@gitster.g","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/4] Add some Glossary terms, and extra renormalize information.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-09T21:34:30Z","receivedAt":"2022-07-09T21:34:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley via GitGitGadget\" writes:\n\n> This short series looks to add the basics of the reachability bitmap and\n> commit graph phrases to the glossary of terms. While these techniques are\n> well known to their developers, for some, they are just magic phrases.\n>\n> The first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]\n\nAvoiding unnecessary TLA is even better than avoiding. As I didn't\nsee in the other three patches that we need to use the OBD acronym,\nperhaps we can omit this step?\n\n> Patch [2/4] provides a basic statement for the Commit-Graph's purpose.\n>\n> Patch [3/4] provides a similar statement for the reachability bitmaps.\n>\n> These two patches maybe misses out on some linking information as to the\n> benefits these have and the basics of their heuristic.\n>\n> Patch [4/4] follows up on a bug report about the lack of idempotence for the\n> `--renormalise' command. See commit message for details.\n>\n> [0] UNA Un-Named Abbreviation.\n>\n> Signed-off-by: Philip Oakley philipoakley@iee.email\n>\n> Philip Oakley (4):\n> glossary: add Object DataBase (ODB) abbreviation\n> glossary: add commit graph description\n> glossary: add reachability bitmap description\n> doc add: renormalize is not idempotent for CRCRLF\n>\n> Documentation/git-add.txt | 3 ++-\n> Documentation/glossary-content.txt | 15 ++++++++++++++-\n> 2 files changed, 16 insertions(+), 2 deletions(-)\n>\n>\n> base-commit: 30cc8d0f147546d4dd77bf497f4dec51e7265bd8\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1282%2FPhilipOakley%2FGlossary_terms-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1282/PhilipOakley/Glossary_terms-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1282\n"},{"id":"458704","messageId":"20220710074848.ku2zobuck6vyim5d@tb-raspi4","threadId":"58125","inReplyTo":"d3b8ed97a105ea1d7e656c964b7eee378e11ede6.1657385781.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2022-07-10T07:48:48Z","receivedAt":"2022-07-10T08:12:05Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Sat, Jul 09, 2022 at 04:56:21PM +0000, Philip Oakley via GitGitGadget wrote:\n> From: Philip Oakley \n>\n> Bug report\n> https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\n> noted that a file containing /r/r/n needed renormalising twice.\n>\n> This is by design. Lone CR characters, not paired with an LF, are left\n> unchanged.\n\nThis is all fine.\n\n> Note the lack of idempotentness of the \"clean\" filter in the\n> documentation.\n\nThe clean filter is idempotent, I would claim, see below.\nYou can run it, and re-run, and re-run, there will no other changes.\nCRLF in the worktree will become LF in the repo,\n'lone CR' stay as they are.\nIn that sense, CRCRLF in the worktree will become CRLF in the repo.\nYou can the renormalize again and again.\n\nThe \"trick\" is that the user has to decide what CRCRLF mean and what\nshould happen in the repo:\nCRCRLF in the worktree becomes one line ending (one LF in the repo)\nor\nCRCRLF in the worktree becomes two line endings ( LFLF in the repo)\n\nFor a) you can use dos2unix twice.\nOr run `git add --renormalize` followed by\n`rm git.bdf`\n`git restore .`\n\nThe thing is that we used a combination of different commands\n$ git add --renormalize .\n$ git commit -m \"Renormalize bdf.txt\"\n$ rm git.bdf\n$ git restore .\n$ git add --renormalize .\n$ git commit -m \"Renormalize a second time bdf.txt\"\n\n... to clean up this very situation.\n\nAnd, if CRCRLF should have become LFLF instead ?\nProbably a python script is needed to fix this.\n(or some other script/program in the language of your choice)\n\nWe could argue that\n`git add --renormalize` is idempotent, but a series of carefully crafted\ncommands is not.\nIn short, what is missing is the documentation how CRCRLF is handled by\nGit.\n\n>\n> Renormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\n> Torsten Bögershausen, 2017-11-16)\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/git-add.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index 11eb70f16c7..c4a5ad11a6b 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -188,7 +188,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n> \tforcibly add them again to the index. This is useful after\n> \tchanging `core.autocrlf` configuration or the `text` attribute\n> \tin order to correct files added with wrong CRLF/LF line endings.\n> -\tThis option implies `-u`.\n\n> +\tThis option implies `-u`. Lone CR characters are untouched, so\n> +\tcleaning not idempotent. A CRCRLF sequence cleans to CRLF.\n\nHow about this:\n\nThis option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\n\n"},{"id":"458716","messageId":"60285079-cb1d-56bf-b36b-e32b3f23158c@iee.email","threadId":"58125","inReplyTo":"xmqqa69it1g9.fsf@gitster.g","subject":"Re: [PATCH 0/4] Add some Glossary terms, and extra renormalize information.","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-07-10T15:20:32Z","receivedAt":"2022-07-10T15:20:40Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 09/07/2022 22:34, Junio C Hamano wrote:\n>> The first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]\n> Avoiding unnecessary TLA is even better than avoiding. As I didn't\n> see in the other three patches that we need to use the OBD acronym,\n> perhaps we can omit this step?\n>\nThis came from seeing `ODB` in a couple of tech docs (commit-graph and\nparallel-checkout) and an 'odb' option in pack-redundant, which I should\nhave noted in the commit message.\n\nI'll update the commit message to clarify that we are using that TLA,\nthough we aren't always consistent in our distinctions between concepts\nand implementation in many places (e.g. Object Store vs Repository;\nStaging area..; etc.)\n\nTLAs, UNAs, etc. have been a bug-bear of mine from doing large\nengineering collaborations.\n\n--\nPhilip\n\n(for completeness;-)\nODB Object Data Base.\nTLA Three Letter Abbreviation.\nUNA Un-Named Abbreviation.\n"},{"id":"458730","messageId":"5551bd33-cf95-3201-0a00-23e02ef41de3@iee.email","threadId":"58125","inReplyTo":"xmqqedyut22w.fsf@gitster.g","subject":"Re: [PATCH 2/4] glossary: add commit graph description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-07-10T21:37:35Z","receivedAt":"2022-07-10T21:37:42Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 09/07/2022 22:20, Junio C Hamano wrote:\n> \"Philip Oakley via GitGitGadget\" writes:\n>\n>> +[[def_commit_graph]]commit graph::\n>> +\tThe commit-graph file is a supplemental data structure that\n>> +\taccelerates commit graph walks. The existing Object Data Base (ODB)\n>> +\tis the definitive commit graph. The \"commit-graph\" file is stored\n>> +\teither in the .git/objects/info directory or in the info directory\n>> +\tof an alternate object database.\n> While it says nothing technically incorrect, I suspect \"The existing\n> object data base is the definitive commit graph\" may invite unneeded\n> confusion.\n\nI probably over-shortened the original text I was summarising\n(technical/commit-graph.txt intro).\n>\n> I think you wanted to say that the DAG formed by traversing the\n> pointers recorded in the objects is the authoritative source of\n> truth and the commit-graph file is merely a precomputed cache\n.. of that graph. *nod*\n> and\n> can be safely lost, \n\nI wasn't particularly thinking of that aspect .. Perhaps more that it\naccelerates commit graph walks..\n> but I am not sure the above description conveys\n> that to anybody who does not already know it.\n>\n> The commits in the object data base form a directed acyclic\n> graph (DAG) by commits referring to their parent commits.\n> Pieces of information from individual commit objects that are\n> needed to traverse the DAG are pre-computed in the commit-graph\n> file and stored in ...\n>\n> is my attempt---I am not very happy or proud about it, but it may be\n> easier to follow.\n\nI wanted to keepseparate from the graph file definition, the rather\nfuzzy relationship between the overall ODB (staging area, and loads of\nother stuff), and the way the DAG is generated, which also needs the\nselected refs to start the traverse..\n\nIn a wider context, it's not clear to me just how the commit graph file\ncontent is chosen relative to the full depth DAG from all local refs.\nThe reachability bit maps have a similar info gap.\n\n--\nPhilip\n\n[sorry for erratic responses - currently isolating with covid]\n\n"},{"id":"458731","messageId":"e45c4fc1-3a30-726c-51f3-00caeca0a552@iee.email","threadId":"58125","inReplyTo":"xmqqilo6t2qy.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-07-10T21:52:45Z","receivedAt":"2022-07-10T21:52:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 09/07/2022 22:06, Junio C Hamano wrote:\n> \"Philip Oakley via GitGitGadget\" writes:\n>\n>> From: Philip Oakley \n>>\n>> Bug report\n>> https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\n>> noted that a file containing /r/r/n needed renormalising twice.\n> Did you mean backslash, not forward?\n\nCorrect. Too many years of Windows.\n>\n>> This is by design. Lone CR characters, not paired with an LF, are left\n>> unchanged. Note the lack of idempotentness of the \"clean\" filter in the\n>> documentation.\n> OK.\n>\n>\n>> Renormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\n>> Torsten Bögershausen, 2017-11-16)\n> Does this need to be said \"HERE\", rather than leaving it to run \"git\n> blame\" for those who became curious?\n\nIt was a misguided reminder to cc Torsten about his recollection of the\nCRCRLF issue. I'll remove it. I see Torsten has also commented.\n>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/git-add.txt | 3 ++-\n>> 1 file changed, 2 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n>> index 11eb70f16c7..c4a5ad11a6b 100644\n>> --- a/Documentation/git-add.txt\n>> +++ b/Documentation/git-add.txt\n>> @@ -188,7 +188,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n>> \tforcibly add them again to the index. This is useful after\n>> \tchanging `core.autocrlf` configuration or the `text` attribute\n>> \tin order to correct files added with wrong CRLF/LF line endings.\n>> -\tThis option implies `-u`.\n>> +\tThis option implies `-u`. Lone CR characters are untouched, so\n>> +\tcleaning *^* not idempotent. A CRCRLF sequence cleans to CRLF.\n> Lack of verb BE somewhere. \n'^' It took me three re-reads to see my mistyping as my head knew what\nI'd meant to write, I've marked above as a note to self.\nAside: Are there any guides / suggestions / how-to's for on-line\nreviewing that you can recommend o\n> Do we expect our readers all understand the math-y word? \nOk. It's mainly used in the test directory, and fsmonitor.h, but not in\nthe user docs.\n\n> It is not\n> too hard to explain it to math-uninitiated, e.g.\n>\n> This option implies `-u`. Note that running renormalize again\n> on the result of running renormalize may make it even \"more\n> normal\". A CR-CR-LF sequence would first renormalize to CR-LF\n> (the first CR, a lone CR, is left intact, and CR-LF that follows\n> normalizes to LF). If you run renormalize again, the resulting\n> CR-LF will normalize down to LF.\n>\nTorsten had a shorter suggestion I'll also look at.\n\nPhilip\n"},{"id":"458734","messageId":"xmqqsfn8pqts.fsf@gitster.g","threadId":"58125","inReplyTo":"e45c4fc1-3a30-726c-51f3-00caeca0a552@iee.email","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-10T22:04:31Z","receivedAt":"2022-07-10T22:04:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n>>> +\tThis option implies `-u`. Lone CR characters are untouched, so\n>>> +\tcleaning *^* not idempotent. A CRCRLF sequence cleans to CRLF.\n>> Lack of verb BE somewhere. \n> '^' It took me three re-reads to see my mistyping as my head knew what\n> I'd meant to write, I've marked above as a note to self.\n> Aside: Are there any guides / suggestions / how-to's for on-line\n> reviewing that you can recommend o\n\nSorry, but I do not know of any good \"trick\" to fight against our\ncommon tendency to easily miss trivial typoes and thinkos in what we\nourselves wrote. We can be surprisingly blind to what a colleague\ncan spot immediately, and that is why it helps to have a thorough\nread-through by a reviewer with fresh eyes. When I was a more\nprolific contributor, I sometimes tried to read aloud what I wrote\nto myself, both docs and code, and caught silly mistakes before\nsending them out to the list, but I do not recommend it to others.\n"},{"id":"458736","messageId":"1b90edd0-3d9d-a741-8865-3968826da315@iee.email","threadId":"58125","inReplyTo":"20220710074848.ku2zobuck6vyim5d@tb-raspi4","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-07-10T22:09:02Z","receivedAt":"2022-07-10T22:09:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Tortsen,\nThanks for the reply and comments.\n\nOn 10/07/2022 08:48, Torsten Bögershausen wrote:\n> On Sat, Jul 09, 2022 at 04:56:21PM +0000, Philip Oakley via GitGitGadget wrote:\n>> From: Philip Oakley \n>>\n>> Bug report\n>> https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\n>> noted that a file containing /r/r/n needed renormalising twice.\n>>\n>> This is by design. Lone CR characters, not paired with an LF, are left\n>> unchanged.\n> This is all fine.\n>\n>> Note the lack of idempotentness of the \"clean\" filter in the\n>> documentation.\n> The clean filter is idempotent, I would claim, see below.\n\nI'd disagree, on the basis that any second 'idempotent' cleaning should\nnot change the file content at all. The need for a second clean was the\nsurprise the user had.\n> You can run it, and re-run, and re-run, there will no other changes.\n> CRLF in the worktree will become LF in the repo,\n> 'lone CR' stay as they are.\n> In that sense, CRCRLF in the worktree will become CRLF in the repo.\nSo  the output isn't normalised, and warning messages ensue (if enabled,\netc)\n> You can the renormalize again and again.\n>\n> The \"trick\" is that the user has to decide what CRCRLF mean and what\n> should happen in the repo\n.. for which they should be forewarned of the issue.\nIn this case it was a large repository transfer of legacy data, so\nlittle knowledge of how the double CRs occured, but it was a real issue\nfor them.\n\n\n> :\n> CRCRLF in the worktree becomes one line ending (one LF in the repo)\n> or\n> CRCRLF in the worktree becomes two line endings ( LFLF in the repo)\n>\n> For a) you can use dos2unix twice.\n> Or run `git add --renormalize` followed by\n> `rm git.bdf`\n> `git restore .`\n>\n> The thing is that we used a combination of different commands\n> $ git add --renormalize .\n> $ git commit -m \"Renormalize bdf.txt\"\n> $ rm git.bdf\n> $ git restore .\n> $ git add --renormalize .\n> $ git commit -m \"Renormalize a second time bdf.txt\"\n>\n> ... to clean up this very situation.\n>\n> And, if CRCRLF should have become LFLF instead ?\n> Probably a python script is needed to fix this.\n> (or some other script/program in the language of your choice)\n>\n> We could argue that\n> `git add --renormalize` is idempotent, but a series of carefully crafted\n> commands is not.\n\n> In short, what is missing is the documentation how CRCRLF is handled by\n> Git.\n*nod*\n>\n>> Renormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\n>> Torsten Bögershausen, 2017-11-16)\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/git-add.txt | 3 ++-\n>> 1 file changed, 2 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n>> index 11eb70f16c7..c4a5ad11a6b 100644\n>> --- a/Documentation/git-add.txt\n>> +++ b/Documentation/git-add.txt\n>> @@ -188,7 +188,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n>> \tforcibly add them again to the index. This is useful after\n>> \tchanging `core.autocrlf` configuration or the `text` attribute\n>> \tin order to correct files added with wrong CRLF/LF line endings.\n>> -\tThis option implies `-u`.\n>> +\tThis option implies `-u`. Lone CR characters are untouched, so\n>> +\tcleaning not idempotent. A CRCRLF sequence cleans to CRLF.\n> How about this:\n>\n> This option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\nThat is probably sufficient. It drops the awkward 'idempotent'. And\nindicates this edge case, though doesn't highlight that the resultant\nCRLF still leaves the file only partially renormalised.\n\nI'll reword.\n>\n\n"},{"id":"458738","messageId":"b9094655-2116-547f-15cb-0a4cce07a960@iee.email","threadId":"58125","inReplyTo":"xmqqsfn8pqts.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-07-10T22:25:32Z","receivedAt":"2022-07-10T22:27:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 10/07/2022 23:04, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n>>>> +\tThis option implies `-u`. Lone CR characters are untouched, so\n>>>> +\tcleaning *^* not idempotent. A CRCRLF sequence cleans to CRLF.\n>>> Lack of verb BE somewhere. \n>> '^' It took me three re-reads to see my mistyping as my head knew what\n>> I'd meant to write, I've marked above as a note to self.\n>> Aside: Are there any guides / suggestions / how-to's for on-line\n>> reviewing that you can recommend o\n> Sorry, but I do not know of any good \"trick\" to fight against our\n> common tendency to easily miss trivial typoes and thinkos in what we\n> ourselves wrote. We can be surprisingly blind to what a colleague\n> can spot immediately, and that is why it helps to have a thorough\n> read-through by a reviewer with fresh eyes. When I was a more\n> prolific contributor, I sometimes tried to read aloud what I wrote\n> to myself, both docs and code, and caught silly mistakes before\n> sending them out to the list, but I do not recommend it to others.\n\nThanks. There does appear to be a lack of literature or articles in this\narea of on-list reviewing\n\nI've not even seen an list of snippets collated from email advice. \nOther than the email etiquette's starter for ten on don't top post ;-)\n\n--\nPhilip\n"},{"id":"460743","messageId":"xmqq5yj6z5rx.fsf@gitster.g","threadId":"58125","inReplyTo":"1b90edd0-3d9d-a741-8865-3968826da315@iee.email","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-05T22:26:10Z","receivedAt":"2022-08-05T22:26:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n>> How about this:\n>>\n>> This option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\n> That is probably sufficient. It drops the awkward 'idempotent'. And\n> indicates this edge case, though doesn't highlight that the resultant\n> CRLF still leaves the file only partially renormalised.\n>\n> I'll reword.\n\nIt's been a few weeks since the last activity on this topic.\nAnything you guys need unblocked to move forward?\n\nThanks.\n\n"},{"id":"460755","messageId":"20220806192225.gu7o2avekbtcg6py@tb-raspi4","threadId":"58125","inReplyTo":"xmqq5yj6z5rx.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2022-08-06T19:22:25Z","receivedAt":"2022-08-06T19:22:44Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Fri, Aug 05, 2022 at 03:26:10PM -0700, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n> >> How about this:\n> >>\n> >> This option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\n> > That is probably sufficient. It drops the awkward 'idempotent'. And\n> > indicates this edge case, though doesn't highlight that the resultant\n> > CRLF still leaves the file only partially renormalised.\n> >\n> > I'll reword.\n>\n> It's been a few weeks since the last activity on this topic.\n> Anything you guys need unblocked to move forward?\n>\n> Thanks.\n>\n\nNot from my point of view. My understanding is, that the short version is OK for\neverybody:\n\nThis option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\n\nIs it OK to ask you for a local ammend to push this further ?\n"},{"id":"460828","messageId":"e454bf85-046d-6205-57e7-4c00b9faa589@iee.email","threadId":"58125","inReplyTo":"xmqq5yj6z5rx.fsf@gitster.g","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-08-08T14:32:35Z","receivedAt":"2022-08-08T14:32:43Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"I've unfortunately had some family issue which prevented me doing any work.\n\nIf I haven't managed anything by the end of the week. I'd be happy if\nothers took it forward.\n\nOn 05/08/2022 23:26, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n>>> How about this:\n>>>\n>>> This option implies `-u`. Lone CR characters are untouched. CRCRLF cleans to CRLF.\n>> That is probably sufficient. It drops the awkward 'idempotent'. And\n>> indicates this edge case, though doesn't highlight that the resultant\n>> CRLF still leaves the file only partially renormalised.\n>>\n>> I'll reword.\n> It's been a few weeks since the last activity on this topic.\n> Anything you guys need unblocked to move forward?\n>\n> Thanks.\n>\n\n"},{"id":"460832","messageId":"xmqq5yj2u2n7.fsf@gitster.g","threadId":"58125","inReplyTo":"e454bf85-046d-6205-57e7-4c00b9faa589@iee.email","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-08T16:21:48Z","receivedAt":"2022-08-08T16:22:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> I've unfortunately had some family issue which prevented me doing any work.\n\nI hope everything will be well on your side.\n\n> If I haven't managed anything by the end of the week. I'd be happy if\n> others took it forward.\n\nThanks for letting us know.\n"},{"id":"460930","messageId":"20220809184409.wypm5gqct6iwq5zo@tb-raspi4","threadId":"58125","inReplyTo":"e454bf85-046d-6205-57e7-4c00b9faa589@iee.email","subject":"Re: [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2022-08-09T18:44:09Z","receivedAt":"2022-08-09T19:07:32Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Mon, Aug 08, 2022 at 03:32:35PM +0100, Philip Oakley wrote:\n> I've unfortunately had some family issue which prevented me doing any work.\n\nThat is sad to here. I hope that things are getting better in one way or another.\n\n>\n> If I haven't managed anything by the end of the week. I'd be happy if\n> others took it forward.\n\nI can certainly have a look, after the weekend, and continue your work.\n\n"},{"id":"460983","messageId":"20220810144450.470-1-philipoakley@iee.email","threadId":"58125","inReplyTo":"xmqq5yj6z5rx.fsf@gitster.g","subject":"[PATCH v2 0/1] .. Add extra renormalize information.","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-08-10T14:44:49Z","receivedAt":"2022-08-10T14:46:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This was [PATCH 4/4] 'doc add: renormalize is not idempotent for CRCRLF'\nof a GitGitGadget series, which was split off into its own branch\npo/doc-add-renormalize\n\nSince V1, remove the use of 'idempotent' which is unknown to many. Instead\nclarify the special case.\n\nPhilip Oakley (1):\n doc add: renormalize is not idempotent for CRCRLF\n\n Documentation/git-add.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\n-- \n2.37.1.windows.1\n\n"},{"id":"460984","messageId":"20220810144450.470-2-philipoakley@iee.email","threadId":"58125","inReplyTo":"20220810144450.470-1-philipoakley@iee.email","subject":"[PATCH v2 1/1] doc add: renormalize is not idempotent for CRCRLF","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-08-10T14:44:50Z","receivedAt":"2022-08-10T14:46:32Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Bug report\n https://lore.kernel.org/git/AM0PR02MB56357CC96B702244F3271014E8DC9@AM0PR02MB5635.eurprd02.prod.outlook.com/\nnoted that a file containing /r/r/n needed renormalising twice.\n\nThis is by design. Lone CR characters, not paired with an LF, are left\nunchanged. Note this limitation of the \"clean\" filter in the documentation.\n\nRenormalize was introduced at 9472935d81e (add: introduce \"--renormalize\",\nTorsten Bögershausen, 2017-11-16)\n\nSigned-off-by: Philip Oakley \n---\nThis is V2 of po/doc-add-renormalize, based on commit dc8c8deaa6\n(Prepare for 2.36.2, 2022-06-07).\nIt was [PATCH 4/4] doc add: renormalize is not idempotent for CRCRLF.\n\ngit send-email \\\n --in-reply-to=xmqq5yj6z5rx.fsf@gitster.g \\\n --to=gitster@pobox.com \\\n --cc=git@vger.kernel.org \\\n --cc=gitgitgadget@gmail.com \\\n --cc=philipoakley@iee.email \\\n --cc=tboegi@web.de \\\n v2-00*\n---\n Documentation/git-add.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 11eb70f16c..9b37f35654 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -188,7 +188,9 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n \tforcibly add them again to the index. This is useful after\n \tchanging `core.autocrlf` configuration or the `text` attribute\n \tin order to correct files added with wrong CRLF/LF line endings.\n-\tThis option implies `-u`.\n+\tThis option implies `-u`. Lone CR characters are untouched, thus\n+\twhile a CRLF cleans to LF, a CRCRLF sequence is only partially\n+\tcleaned to CRLF.\n \n --chmod=(+|-)x::\n \tOverride the executable bit of the added files. The executable\n-- \n2.37.1.windows.1\n\n"},{"id":"461007","messageId":"20220810171121.qwuiipheotx2bwaq@tb-raspi4","threadId":"58125","inReplyTo":"20220810144450.470-2-philipoakley@iee.email","subject":"Re: [PATCH v2 1/1] doc add: renormalize is not idempotent for CRCRLF","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2022-08-10T17:11:21Z","receivedAt":"2022-08-10T17:11:55Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"[]\n\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index 11eb70f16c..9b37f35654 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -188,7 +188,9 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n> \tforcibly add them again to the index. This is useful after\n> \tchanging `core.autocrlf` configuration or the `text` attribute\n> \tin order to correct files added with wrong CRLF/LF line endings.\n> -\tThis option implies `-u`.\n> +\tThis option implies `-u`. Lone CR characters are untouched, thus\n> +\twhile a CRLF cleans to LF, a CRCRLF sequence is only partially\n> +\tcleaned to CRLF.\n\nThanks, I think this one looks good to me.\nReviewed-by: Torsten Bögershausen \n"},{"id":"461010","messageId":"xmqqh72km1vp.fsf@gitster.g","threadId":"58125","inReplyTo":"20220810144450.470-2-philipoakley@iee.email","subject":"Re: [PATCH v2 1/1] doc add: renormalize is not idempotent for CRCRLF","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-10T17:42:18Z","receivedAt":"2022-08-10T17:42:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index 11eb70f16c..9b37f35654 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -188,7 +188,9 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n> \tforcibly add them again to the index. This is useful after\n> \tchanging `core.autocrlf` configuration or the `text` attribute\n> \tin order to correct files added with wrong CRLF/LF line endings.\n> -\tThis option implies `-u`.\n> +\tThis option implies `-u`. Lone CR characters are untouched, thus\n> +\twhile a CRLF cleans to LF, a CRCRLF sequence is only partially\n> +\tcleaned to CRLF.\n\nLooks perfetly readable and understandable to me.\n\nThanks, will replace. Let's plan to merge it down soonish.\n\n\n"},{"id":"462201","messageId":"70706e55-07b5-5fec-df06-9953e0013a8e@iee.email","threadId":"58125","inReplyTo":"5551bd33-cf95-3201-0a00-23e02ef41de3@iee.email","subject":"Re: [PATCH 2/4] glossary: add commit graph description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-08-30T14:33:40Z","receivedAt":"2022-08-30T14:33:48Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 10/07/2022 22:37, Philip Oakley wrote:\n> Hi Junio,\n>\n> On 09/07/2022 22:20, Junio C Hamano wrote:\n>> \"Philip Oakley via GitGitGadget\" writes:\n>>\n>>> +[[def_commit_graph]]commit graph::\n>>> +\tThe commit-graph file is a supplemental data structure that\n>>> +\taccelerates commit graph walks. The existing Object Data Base (ODB)\n>>> +\tis the definitive commit graph. The \"commit-graph\" file is stored\n>>> +\teither in the .git/objects/info directory or in the info directory\n>>> +\tof an alternate object database.\n>> While it says nothing technically incorrect, I suspect \"The existing\n>> object data base is the definitive commit graph\" may invite unneeded\n>> confusion.\n> I probably over-shortened the original text I was summarising\n> (technical/commit-graph.txt intro).\n\nI was looking to outline the concept and how, therefore, it is different\nfrom the reachability bitmaps, and also from the 'canonical' DAG of\nGit's commit objects.\n\nI hope to have another go in a couple of weeks time.\n\n>> I think you wanted to say that the DAG formed by traversing the\n>> pointers recorded in the objects is the authoritative source of\n>> truth and the commit-graph file is merely a precomputed cache\n> .. of that graph. *nod*\n>> and\n>> can be safely lost, \n> I wasn't particularly thinking of that aspect .. Perhaps more that it\n> accelerates commit graph walks..\n>> but I am not sure the above description conveys\n>> that to anybody who does not already know it.\n>>\n>> The commits in the object data base form a directed acyclic\n>> graph (DAG) by commits referring to their parent commits.\n>> Pieces of information from individual commit objects that are\n>> needed to traverse the DAG are pre-computed in the commit-graph\n>> file and stored in ...\n>>\n>> is my attempt---I am not very happy or proud about it, but it may be\n>> easier to follow.\n> I wanted to keepseparate from the graph file definition, the rather\n> fuzzy relationship between the overall ODB (staging area, and loads of\n> other stuff), and the way the DAG is generated, which also needs the\n> selected refs to start the traverse..\n>\n> In a wider context, it's not clear to me just how the commit graph file\n> content is chosen relative to the full depth DAG from all local refs.\n> The reachability bit maps have a similar info gap.\n>\n> --\n> Philip\n>\n> [sorry for erratic responses - currently isolating with covid]\n>\n\n"},{"id":"465583","messageId":"20221022222539.2333-3-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221022222539.2333-1-philipoakley@iee.email","subject":"[PATCH v2 2/3] glossary: add \"commit graph\" description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-22T22:25:38Z","receivedAt":"2022-10-22T22:26:55Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Git has an additional \"commit graph\" capability that supplements the\nnormal commit object's directed acylic graph (DAG). The supplemental\ncommit graph file is designed for speed of access.\n\nDescribe the commit graph both from the normative DAG view point and\nfrom the commit graph file perspective.\n\nAlso, clarify the link between the branch ref and branch tip\nby linking to the `ref` glossary entry, matching this commit graph\nentry.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 17 ++++++++++++++++-\n 1 file changed, 16 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 947ac49606..97050826e5 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -20,7 +20,7 @@\n [[def_branch]]branch::\n \tA \"branch\" is a line of development. The most recent\n \t<> on a branch is referred to as the tip of\n-\tthat branch. The tip of the branch is referenced by a branch\n+\tthat branch. The tip of the branch is <> by a branch\n \t<>, which moves forward as additional development\n \tis done on the branch. A single Git\n \t<> can track an arbitrary number of\n@@ -75,6 +75,21 @@ state in the Git history, by creating a new commit representing the current\n state of the <> and advancing <>\n to point at the new commit.\n \n+[[def_commit_graph_general]]commit graph concept, representations and usage::\n+\tA synonym for the <> structure formed by\n+\tthe commits in the object database, <> by branch tips,\n+\tusing their <> of linked commits.\n+\tThis structure is the definitive commit graph. The\n+\tgraph can be represented in other ways, e.g. the\n+\t<>.\n+\n+[[def_commit_graph_file]]commit graph file::\n+\tThe commit-graph file is a supplemental representation of\n+\tthe <> which accelerates\n+\tcommit graph walks. The \"commit-graph\" file is stored\n+\teither in the .git/objects/info directory or in the info directory\n+\tof an alternate object database.\n+\n [[def_commit_object]]commit object::\n \tAn <> which contains the information about a\n \tparticular <>, such as <>, committer,\n-- \n2.38.1.windows.1\n\n"},{"id":"465584","messageId":"20221022222539.2333-4-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221022222539.2333-1-philipoakley@iee.email","subject":"[PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-22T22:25:39Z","receivedAt":"2022-10-22T22:27:00Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Describe the purpose of the reachability bitmap.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 97050826e5..3d67b452aa 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -508,6 +508,14 @@ exclude;;\n \t<> to the trees or <>\n \tthat they contain.\n \n+[[def_reachability_bitmap]]reachability bitmaps::\n+\tReachability bitmaps store information about the\n+\t<> of a selected set of objects in\n+\ta packfile, or a multi-pack index (MIDX) to speed up object search.\n+\tA repository may have at\n+\tmost one bitmap. The bitmap may belong to either one pack, or the\n+\trepository's multi-pack index (if it exists).\n+\n [[def_rebase]]rebase::\n \tTo reapply a series of changes from a <> to a\n \tdifferent base, and reset the <> of that branch\n-- \n2.38.1.windows.1\n\n"},{"id":"465585","messageId":"20221022222539.2333-2-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221022222539.2333-1-philipoakley@iee.email","subject":"[PATCH v2 1/3] doc: use 'object database' not ODB or abbreviation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-22T22:25:37Z","receivedAt":"2022-10-22T22:27:00Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The abbreviation 'ODB' is used in the technical documentation\nsections for commit-graph and parallel-checkout, along with an\n'odb' option in `git-pack-redundant`, without expansion.\n\nUse 'object database' in full, in those entries. The text has not\nbeen reflowed to keep the changes minimal.\n\nWhile in the glossary for `object` terms, add the common`oid`\nabbreviation to its entry.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/glossary-content.txt | 2 +-\n Documentation/technical/commit-graph.txt | 2 +-\n Documentation/technical/parallel-checkout.txt | 2 +-\n 4 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e5..1132c73956 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -34,7 +34,7 @@ OPTIONS\n \n --alt-odb::\n \tDon't require objects present in packs from alternate object\n-\tdirectories to be present in local packs.\n+\tdatabase (odb) directories to be present in local packs.\n \n --verbose::\n \tOutputs some statistics to stderr. Has a small performance penalty.\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex aa2f41f5e7..947ac49606 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -262,7 +262,7 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \tidentified by its <>. The objects usually\n \tlive in `$GIT_DIR/objects/`.\n \n-[[def_object_identifier]]object identifier::\n+[[def_object_identifier]]object identifier (oid)::\n \tSynonym for <>.\n \n [[def_object_name]]object name::\ndiff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt\nindex f05e7bda1a..5a4e1eba8b 100644\n--- a/Documentation/technical/commit-graph.txt\n+++ b/Documentation/technical/commit-graph.txt\n@@ -17,7 +17,7 @@ There are two main costs here:\n \n The commit-graph file is a supplemental data structure that accelerates\n commit graph walks. If a user downgrades or disables the 'core.commitGraph'\n-config setting, then the existing ODB is sufficient. The file is stored\n+config setting, then the existing object database is sufficient. The file is stored\n as \"commit-graph\" either in the .git/objects/info directory or in the info\n directory of an alternate.\n \ndiff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt\nindex e790258a1a..47c9b6183c 100644\n--- a/Documentation/technical/parallel-checkout.txt\n+++ b/Documentation/technical/parallel-checkout.txt\n@@ -56,7 +56,7 @@ Rejected Multi-Threaded Solution\n \n The most \"straightforward\" implementation would be to spread the set of\n to-be-updated cache entries across multiple threads. But due to the\n-thread-unsafe functions in the ODB code, we would have to use locks to\n+thread-unsafe functions in the object database code, we would have to use locks to\n coordinate the parallel operation. An early prototype of this solution\n showed that the multi-threaded checkout would bring performance\n improvements over the sequential code, but there was still too much lock\n-- \n2.38.1.windows.1\n\n"},{"id":"465586","messageId":"20221022222539.2333-1-philipoakley@iee.email","threadId":"58125","inReplyTo":"pull.1282.git.1657385781.gitgitgadget@gmail.com","subject":"[PATCH v2 0/3] Add some Glossary of terms information","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-22T22:25:36Z","receivedAt":"2022-10-22T22:27:03Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"was GitGitGadget #1282,\n(in reply to )\n\nThis short series looks to add the basics of the reachability bitmap\nand commit graph phrases to the glossary of terms. While these\ntechniques are well known to their developers, for some, they are\njust magic phrases.\n\n[V2] .. since V1\nPatch 4/4 has been taken upstream independently, and hence dropped\nhere so we're now just [n/3].\n\nPatch 1/3 Dropped the glossary addition in favour of changing the\nlocations that used ODB (Junio's suggestion). Kept the git\npack-redundant's `--alt-odb` but spelt out 'object database' in full\nin the man page. The only remaining `odb`s are within `goodbye` ;-).\n\nWhile here, add the (oid) abbreviation to its adjacent entry.\n\nPatch 2/3 Split the 'commit-graph' explanation into two parts to\ndistinguish the speed-up option, from Git's core graph concept of\nobject traversal. Included links to existing terms.\n\nPatch 3/3 Added links to existing terms. Statement for the\nreachability bitmaps.\n\nadded cc: for Stolee (commit-graph) and Abhradeep Chakraborty\n(Bitmaps) review.\n\n\n[V1] [GGG PR #1282] \nhttps://lore.kernel.org/git/pull.1282.git.1657385781.gitgitgadget@gmail.com/\n\nThe first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]\n\nPatch [2/4] provides a basic statement for the Commit-Graph's purpose.\n\nPatch [3/4] provides a similar statement for the reachability bitmaps.\n\nThese two patches maybe misses out on some linking information as to\nthe benefits these have and the basics of their heuristic.\n\nPatch [4/4] follows up on a bug report about the lack of idempotence\nfor the `--renormalise' command. See commit message for details.\n\n[0] UNA Un-Named Abbreviation.\n\nSigned-off-by: Philip Oakley philipoakley@iee.email\ncc: Philip Oakley philipoakley@iee.email\n\n\nPhilip Oakley (3):\n doc: use 'object database' not ODB or abbreviation\n glossary: add \"commit graph\" description\n glossary: add reachability bitmap description\n\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/glossary-content.txt | 27 +++++++++++++++++--\n Documentation/technical/commit-graph.txt | 2 +-\n Documentation/technical/parallel-checkout.txt | 2 +-\n 4 files changed, 28 insertions(+), 5 deletions(-)\n\nRange-diff against v1:\n1: 51b55828d5 ! 1: dc0d934b00 glossary: add Object DataBase (ODB) abbreviation\n @@ Metadata\n Author: Philip Oakley \n \n ## Commit message ##\n - glossary: add Object DataBase (ODB) abbreviation\n + doc: use 'object database' not ODB or abbreviation\n \n - ODB abbreviation is used in the technical section without expansion.\n - Show the abbreviation in the Glossary.\n + The abbreviation 'ODB' is used in the technical documentation\n + sections for commit-graph and parallel-checkout, along with an\n + 'odb' option in `git-pack-redundant`, without expansion.\n +\n + Use 'object database' in full, in those entries. The text has not\n + been reflowed to keep the changes minimal.\n +\n + While in the glossary for `object` terms, add the common`oid`\n + abbreviation to its entry.\n \n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n +\n + ## Documentation/git-pack-redundant.txt ##\n +@@ Documentation/git-pack-redundant.txt: OPTIONS\n + \n + --alt-odb::\n + \tDon't require objects present in packs from alternate object\n +-\tdirectories to be present in local packs.\n ++\tdatabase (odb) directories to be present in local packs.\n + \n + --verbose::\n + \tOutputs some statistics to stderr. Has a small performance penalty.\n \n ## Documentation/glossary-content.txt ##\n @@ Documentation/glossary-content.txt: This commit is referred to as a \"merge commit\", or sometimes just a\n - \t<> of its contents. Consequently, an\n - \tobject cannot be changed.\n - \n --[[def_object_database]]object database::\n -+[[def_object_database]]object database (ODB)::\n - \tStores a set of \"objects\", and an individual <> is\n \tidentified by its <>. The objects usually\n \tlive in `$GIT_DIR/objects/`.\n + \n +-[[def_object_identifier]]object identifier::\n ++[[def_object_identifier]]object identifier (oid)::\n + \tSynonym for <>.\n + \n + [[def_object_name]]object name::\n +\n + ## Documentation/technical/commit-graph.txt ##\n +@@ Documentation/technical/commit-graph.txt: There are two main costs here:\n + \n + The commit-graph file is a supplemental data structure that accelerates\n + commit graph walks. If a user downgrades or disables the 'core.commitGraph'\n +-config setting, then the existing ODB is sufficient. The file is stored\n ++config setting, then the existing object database is sufficient. The file is stored\n + as \"commit-graph\" either in the .git/objects/info directory or in the info\n + directory of an alternate.\n + \n +\n + ## Documentation/technical/parallel-checkout.txt ##\n +@@ Documentation/technical/parallel-checkout.txt: Rejected Multi-Threaded Solution\n + \n + The most \"straightforward\" implementation would be to spread the set of\n + to-be-updated cache entries across multiple threads. But due to the\n +-thread-unsafe functions in the ODB code, we would have to use locks to\n ++thread-unsafe functions in the object database code, we would have to use locks to\n + coordinate the parallel operation. An early prototype of this solution\n + showed that the multi-threaded checkout would bring performance\n + improvements over the sequential code, but there was still too much lock\n2: 6a88bdb7ed ! 2: 77fbf889a5 glossary: add commit graph description\n @@ Metadata\n Author: Philip Oakley \n \n ## Commit message ##\n - glossary: add commit graph description\n + glossary: add \"commit graph\" description\n +\n + Git has an additional \"commit graph\" capability that supplements the\n + normal commit object's directed acylic graph (DAG). The supplemental\n + commit graph file is designed for speed of access.\n +\n + Describe the commit graph both from the normative DAG view point and\n + from the commit graph file perspective.\n +\n + Also, clarify the link between the branch ref and branch tip\n + by linking to the `ref` glossary entry, matching this commit graph\n + entry.\n \n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n \n ## Documentation/glossary-content.txt ##\n +@@\n + [[def_branch]]branch::\n + \tA \"branch\" is a line of development. The most recent\n + \t<> on a branch is referred to as the tip of\n +-\tthat branch. The tip of the branch is referenced by a branch\n ++\tthat branch. The tip of the branch is <> by a branch\n + \t<>, which moves forward as additional development\n + \tis done on the branch. A single Git\n + \t<> can track an arbitrary number of\n @@ Documentation/glossary-content.txt: state in the Git history, by creating a new commit representing the current\n state of the <> and advancing <>\n to point at the new commit.\n \n -+[[def_commit_graph]]commit graph::\n -+\tThe commit-graph file is a supplemental data structure that\n -+\taccelerates commit graph walks. The existing Object Data Base (ODB)\n -+\tis the definitive commit graph. The \"commit-graph\" file is stored\n ++[[def_commit_graph_general]]commit graph concept, representations and usage::\n ++\tA synonym for the <> structure formed by\n ++\tthe commits in the object database, <> by branch tips,\n ++\tusing their <> of linked commits.\n ++\tThis structure is the definitive commit graph. The\n ++\tgraph can be represented in other ways, e.g. the\n ++\t<>.\n ++\n ++[[def_commit_graph_file]]commit graph file::\n ++\tThe commit-graph file is a supplemental representation of\n ++\tthe <> which accelerates\n ++\tcommit graph walks. The \"commit-graph\" file is stored\n +\teither in the .git/objects/info directory or in the info directory\n +\tof an alternate object database.\n +\n3: 564de4c68f ! 3: fde2c58153 glossary: add reachability bitmap description\n @@ Metadata\n ## Commit message ##\n glossary: add reachability bitmap description\n \n + Describe the purpose of the reachability bitmap.\n +\n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n \n ## Documentation/glossary-content.txt ##\n @@ Documentation/glossary-content.txt: exclude;;\n @@ Documentation/glossary-content.txt: exclude;;\n \tthat they contain.\n \n +[[def_reachability_bitmap]]reachability bitmaps::\n -+\tReachability bitmaps store information about the set of objects in\n -+\ta packfile, or a multi-pack index (MIDX). A repository may have at\n ++\tReachability bitmaps store information about the\n ++\t<> of a selected set of objects in\n ++\ta packfile, or a multi-pack index (MIDX) to speed up object search.\n ++\tA repository may have at\n +\tmost one bitmap. The bitmap may belong to either one pack, or the\n +\trepository's multi-pack index (if it exists).\n +\n\n-- \n2.38.1.windows.1\n\n"},{"id":"465594","messageId":"xmqqpmejfgxf.fsf@gitster.g","threadId":"58125","inReplyTo":"20221022222539.2333-1-philipoakley@iee.email","subject":"Re: [PATCH v2 0/3] Add some Glossary of terms information","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-23T01:49:00Z","receivedAt":"2022-10-23T01:49:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> was GitGitGadget #1282,\n> (in reply to )\n>\n> This short series looks to add the basics of the reachability bitmap\n> and commit graph phrases to the glossary of terms. While these\n> techniques are well known to their developers, for some, they are\n> just magic phrases.\n\nThey all looked reasonable to me, but as you sensibly Cc'ed folks\nwho worked on the areas the concepts explained in these patches are\nthe most relevant, these patches would benefit from their inputs, so\nlet's hear them first and then advance the patches to 'next'.\n\nThanks.\n"},{"id":"465607","messageId":"CAPOJW5zmYC9q8+aXh9-kZnvT28GQ1ud3LenFi9qxV4DVdCWKxg@mail.gmail.com","threadId":"58125","inReplyTo":"20221022222539.2333-4-philipoakley@iee.email","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Abhradeep Chakraborty","fromEmail":"chakrabortyabhradeep79@gmail.com","sentAt":"2022-10-24T07:43:46Z","receivedAt":"2022-10-24T07:44:54Z","isPatch":true,"sender":{"key":"chakrabortyabhradeep79@gmail.com","avatar":"https://avatars.githubusercontent.com/u/75240995?v=4"},"body":"Hey Philip,\nGlad that you're working on this :)\n\nOn Sun, Oct 23, 2022 at 3:55 AM Philip Oakley wrote:\n>\n> Describe the purpose of the reachability bitmap.\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/glossary-content.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 97050826e5..3d67b452aa 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -508,6 +508,14 @@ exclude;;\n> <> to the trees or <>\n> that they contain.\n>\n> +[[def_reachability_bitmap]]reachability bitmaps::\n> + Reachability bitmaps store information about the\n> + <> of a selected set of objects in\n> + a packfile, or a multi-pack index (MIDX) to speed up object search.\n\nLooks good to me. Initially I thought that we could explain it more\nbut as you already linked the \"reachability\" here, we don't need to.\n\n> + A repository may have at\n> + most one bitmap. The bitmap may belong to either one pack, or the\n> + repository's multi-pack index (if it exists).\n> +\n\nSmall correction here - A repository may have multiple bitmaps (one\nfor each selected commit from the preferred packfile or a\nmulti-pack-index) but it can have only one \".bitmap\" file (as of now).\nBitmaps for the selected commits are stored in that \".bitmap\" file.\nSo I think the below lines (or similar) will work -\n\n The bitmaps are stored in a \".bitmap\" file. A repository may have\n at most one \".bitmap\" file. The file may belong to either one pack, or the\n repository's multi-pack-index (if it exists).\n\nFeel free to rephrase it accordingly.\n\nThanks :)\n"},{"id":"465635","messageId":"xmqq1qqxuqf0.fsf@gitster.g","threadId":"58125","inReplyTo":"CAPOJW5zmYC9q8+aXh9-kZnvT28GQ1ud3LenFi9qxV4DVdCWKxg@mail.gmail.com","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-24T16:39:31Z","receivedAt":"2022-10-24T20:38:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Abhradeep Chakraborty writes:\n\n> Small correction here - A repository may have multiple bitmaps (one\n> for each selected commit from the preferred packfile or a\n> multi-pack-index) but it can have only one \".bitmap\" file (as of now).\n> Bitmaps for the selected commits are stored in that \".bitmap\" file.\n> So I think the below lines (or similar) will work -\n>\n> The bitmaps are stored in a \".bitmap\" file. A repository may have\n> at most one \".bitmap\" file. The file may belong to either one pack, or the\n> repository's multi-pack-index (if it exists).\n>\n> Feel free to rephrase it accordingly.\n\nSounds good to me. Or Philip's original can be tweaked minimally to\nsay \"... may have at most one bitmap file (which stores multiple\nbitmaps)\".\n\nThanks.\n"},{"id":"465659","messageId":"746491f4-fb41-92fe-7360-20a845dc21fc@iee.email","threadId":"58125","inReplyTo":"xmqq1qqxuqf0.fsf@gitster.g","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-24T21:23:37Z","receivedAt":"2022-10-24T23:03:21Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 24/10/2022 17:39, Junio C Hamano wrote:\n> Abhradeep Chakraborty writes:\n>\n>> Small correction here - A repository may have multiple bitmaps (one\n>> for each selected commit from the preferred packfile or a\n>> multi-pack-index) but it can have only one \".bitmap\" file (as of now).\n>> Bitmaps for the selected commits are stored in that \".bitmap\" file.\n>> So I think the below lines (or similar) will work -\n>>\n>> The bitmaps are stored in a \".bitmap\" file. A repository may have\n>> at most one \".bitmap\" file. The file may belong to either one pack, or the\n>> repository's multi-pack-index (if it exists).\n>>\n>> Feel free to rephrase it accordingly.\n> Sounds good to me. Or Philip's original can be tweaked minimally to\n> say \"... may have at most one bitmap file (which stores multiple\n> bitmaps)\".\n>\nThanks both. I'll tweak the description in a day or so to allow Stolee\nto comment if required.\nP.\n"},{"id":"465703","messageId":"3a7f43bd-2c48-6a37-7602-f4c938f7f58e@github.com","threadId":"58125","inReplyTo":"20221022222539.2333-3-philipoakley@iee.email","subject":"Re: [PATCH v2 2/3] glossary: add \"commit graph\" description","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-10-25T12:31:58Z","receivedAt":"2022-10-25T12:32:05Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 10/22/2022 6:25 PM, Philip Oakley wrote:\n> Git has an additional \"commit graph\" capability that supplements the\n> normal commit object's directed acylic graph (DAG). The supplemental\n> commit graph file is designed for speed of access.\n> \n> Describe the commit graph both from the normative DAG view point and\n> from the commit graph file perspective.\n\nOne way to help keep the general term and the file separate is to use\ndifferent notation. \"commit graph\" (with a space, no formatting) is the\nDAG. \"`commit-graph`\" (with a dash, code formatting) is the file (and\nits format).\n\n> +[[def_commit_graph_general]]commit graph concept, representations and usage::\n> +\tA synonym for the <> structure formed by\n> +\tthe commits in the object database, <> by branch tips,\n> +\tusing their <> of linked commits.\n> +\tThis structure is the definitive commit graph. The\n> +\tgraph can be represented in other ways, e.g. the\n> +\t<>.\n> +\n> +[[def_commit_graph_file]]commit graph file::\n> +\tThe commit-graph file is a supplemental representation of\n> +\tthe <> which accelerates\n> +\tcommit graph walks. The \"commit-graph\" file is stored\n> +\teither in the .git/objects/info directory or in the info directory\n> +\tof an alternate object database.\n> +\n\nSo this would become:\n\n[[def_commit_graph_file]]`commit-graph` file::\n\tThe `commit-graph` file is a supplemental representation of\n\tthe <> which accelerates\n\tcommit graph walks. The `commit-graph` file is stored either in\n\tthe `.git/objects/info` directory or in the `info` directory of\n\tan alternate object database.\n\n(I did some extra style and word-wrapping changes, too.)\n\nOther than these nits, I find this to be a clear description.\n\nThanks,\n-Stolee\n"},{"id":"465704","messageId":"c9e90df3-6f70-6422-00db-beb7afda0439@github.com","threadId":"58125","inReplyTo":"746491f4-fb41-92fe-7360-20a845dc21fc@iee.email","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-10-25T12:34:52Z","receivedAt":"2022-10-25T12:35:03Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 10/24/2022 5:23 PM, Philip Oakley wrote:\n> On 24/10/2022 17:39, Junio C Hamano wrote:\n>> Abhradeep Chakraborty writes:\n>>\n>>> Small correction here - A repository may have multiple bitmaps (one\n>>> for each selected commit from the preferred packfile or a\n>>> multi-pack-index) but it can have only one \".bitmap\" file (as of now).\n>>> Bitmaps for the selected commits are stored in that \".bitmap\" file.\n>>> So I think the below lines (or similar) will work -\n>>>\n>>> The bitmaps are stored in a \".bitmap\" file. A repository may have\n>>> at most one \".bitmap\" file. The file may belong to either one pack, or the\n>>> repository's multi-pack-index (if it exists).\n>>>\n>>> Feel free to rephrase it accordingly.\n>> Sounds good to me. Or Philip's original can be tweaked minimally to\n>> say \"... may have at most one bitmap file (which stores multiple\n>> bitmaps)\".\n>>\n> Thanks both. I'll tweak the description in a day or so to allow Stolee\n> to comment if required.\n\nI added my comments about the commit-graph file, and agree with\nAbhradeep's suggestions here.\n\nAdding Taylor as a possible reviewer, too.\n\nThe one thing I will say is that there can be multiple .bitmap\nfiles, but Git will only use one of them. Not sure if that is\nworth being pedantic about here, though.\n\nWe'll need to keep this glossary section in mind in case things\nchange (such as \"at most one bitmap file\").\n\nThanks,\n-Stolee\n"},{"id":"465712","messageId":"xmqqpmefoq6u.fsf@gitster.g","threadId":"58125","inReplyTo":"c9e90df3-6f70-6422-00db-beb7afda0439@github.com","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-25T15:53:13Z","receivedAt":"2022-10-25T15:53:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Derrick Stolee writes:\n\n> The one thing I will say is that there can be multiple .bitmap\n> files, but Git will only use one of them. Not sure if that is\n> worth being pedantic about here, though.\n\nThat matches my understanding, but \"can be\" is less of the norm\nthese days, no? \"repack -b\" would refuse without \"-a\" so we may\nhave more than one by accident, or am I missing a common scenario\nthat we do perfectly normal things and still end up with multiple?\n\nI agree with you that it probably is a good idea to say there can\nbe, so that the readers do not have to alarmed.\n\n Only one '.bitmap' file (which stores multiple reachability\n bitmaps) per repository is used in a repository (note. it is\n not wrong to have more than one). The bitmap file may belong\n to either one pack, or the repository's multi-pack index (if\n it exists).\n\nBut then the readers who do have more than one would next think \"how\ndo I get rid of the ones that are not used? they are wasting my\nprecious disk space\". So I also am not sure if it helps to write\nmore. \"It is generally true that..\" white lie may be better than\ntechnical correctness in this case.\n\n> We'll need to keep this glossary section in mind in case things\n> change (such as \"at most one bitmap file\").\n\nTrue.\n\nThanks.\n"},{"id":"466015","messageId":"d7c818c8-201d-e7d3-f0b9-6d01ab51043c@iee.email","threadId":"58125","inReplyTo":"3a7f43bd-2c48-6a37-7602-f4c938f7f58e@github.com","subject":"Re: [PATCH v2 2/3] glossary: add \"commit graph\" description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:32:47Z","receivedAt":"2022-10-29T16:32:54Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 25/10/2022 13:31, Derrick Stolee wrote:\n> On 10/22/2022 6:25 PM, Philip Oakley wrote:\n>> Git has an additional \"commit graph\" capability that supplements the\n>> normal commit object's directed acylic graph (DAG). The supplemental\n>> commit graph file is designed for speed of access.\n>>\n>> Describe the commit graph both from the normative DAG view point and\n>> from the commit graph file perspective.\n> One way to help keep the general term and the file separate is to use\n> different notation. \"commit graph\" (with a space, no formatting) is the\n> DAG. \"`commit-graph`\" (with a dash, code formatting) is the file (and\n> its format).\nI did want to have separate entries to make clear the distinction at\nthis level.\n\nThe use of the hyphenation is good, and there are only a few places\nwhere that isn't followed, so I'll specifically call out the use of\nhyphenation, and add a patch to update the few places that used the\ngeneric term inappropriately.\nUsing the code formatting for commit-graph would have been extensive.,\n\n>> +[[def_commit_graph_general]]commit graph concept, representations and usage::\n>> +\tA synonym for the <> structure formed by\n>> +\tthe commits in the object database, <> by branch tips,\n>> +\tusing their <> of linked commits.\n>> +\tThis structure is the definitive commit graph. The\n>> +\tgraph can be represented in other ways, e.g. the\n>> +\t<>.\n>> +\n>> +[[def_commit_graph_file]]commit graph file::\n>> +\tThe commit-graph file is a supplemental representation of\n>> +\tthe <> which accelerates\n>> +\tcommit graph walks. The \"commit-graph\" file is stored\n>> +\teither in the .git/objects/info directory or in the info directory\n>> +\tof an alternate object database.\n>> +\n> So this would become:\n>\n> [[def_commit_graph_file]]`commit-graph` file::\n> \tThe `commit-graph` file is a supplemental representation of\n> \tthe <> which accelerates\n> \tcommit graph walks. The `commit-graph` file is stored either in\n> \tthe `.git/objects/info` directory or in the `info` directory of\n> \tan alternate object database.\n>\n> (I did some extra style and word-wrapping changes, too.)\n\nI've used some of that. Thanks.\n\nPhilip\n>\n> Other than these nits, I find this to be a clear description.\n>\n> Thanks,\n> -Stolee\n\n"},{"id":"466016","messageId":"c49fce45-bbd6-a456-234c-7f9709ae4d51@iee.email","threadId":"58125","inReplyTo":"c9e90df3-6f70-6422-00db-beb7afda0439@github.com","subject":"Re: [PATCH v2 3/3] glossary: add reachability bitmap description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:36:40Z","receivedAt":"2022-10-29T16:36:55Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 25/10/2022 13:34, Derrick Stolee wrote:\n> On 10/24/2022 5:23 PM, Philip Oakley wrote:\n>> On 24/10/2022 17:39, Junio C Hamano wrote:\n>>> Abhradeep Chakraborty writes:\n>>>\n>>>> Small correction here - A repository may have multiple bitmaps (one\n>>>> for each selected commit from the preferred packfile or a\n>>>> multi-pack-index) but it can have only one \".bitmap\" file (as of now).\n>>>> Bitmaps for the selected commits are stored in that \".bitmap\" file.\n>>>> So I think the below lines (or similar) will work -\n>>>>\n>>>> The bitmaps are stored in a \".bitmap\" file. A repository may have\n>>>> at most one \".bitmap\" file. The file may belong to either one pack, or the\n>>>> repository's multi-pack-index (if it exists).\n>>>>\n>>>> Feel free to rephrase it accordingly.\n>>> Sounds good to me. Or Philip's original can be tweaked minimally to\n>>> say \"... may have at most one bitmap file (which stores multiple\n>>> bitmaps)\".\n>>>\n>> Thanks both. I'll tweak the description in a day or so to allow Stolee\n>> to comment if required.\n> I added my comments about the commit-graph file, and agree with\n> Abhradeep's suggestions here.\n>\n> Adding Taylor as a possible reviewer, too.\n>\n> The one thing I will say is that there can be multiple .bitmap\n> files, but Git will only use one of them. Not sure if that is\n> worth being pedantic about here, though.\n>\n> We'll need to keep this glossary section in mind in case things\n> change (such as \"at most one bitmap file\").\n>\n> Thanks,\n> -Stolee\nI've gone with the phrase \"at most one bitmap file in use.\" here.\n\nThe updated series should be sent shortly.\n\nPhilip.\n"},{"id":"466017","messageId":"20221029164112.2097-3-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221029164112.2097-1-philipoakley@iee.email","subject":"[PATCH v3 2/4] glossary: add \"commit graph\" description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:41:10Z","receivedAt":"2022-10-29T16:41:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Git has an additional \"commit graph\" capability that supplements the\nnormal commit object's directed acyclic graph (DAG). The supplemental\ncommit graph file is designed for speed of access.\n\nDescribe the commit graph both from the normative DAG view point and\nfrom the commit graph file perspective.\n\nAlso, clarify the link between the branch ref and branch tip\nby linking to the `ref` glossary entry, matching this commit graph\nentry.\n\nThe commit-graph file is also distinguished by its hyphenation.\n\nSubsequent commit catches the few cases where the hyphenation of\ncommit-graph was missing.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 17 ++++++++++++++++-\n 1 file changed, 16 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 947ac49606..a526710278 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -20,7 +20,7 @@\n [[def_branch]]branch::\n \tA \"branch\" is a line of development. The most recent\n \t<> on a branch is referred to as the tip of\n-\tthat branch. The tip of the branch is referenced by a branch\n+\tthat branch. The tip of the branch is <> by a branch\n \t<>, which moves forward as additional development\n \tis done on the branch. A single Git\n \t<> can track an arbitrary number of\n@@ -75,6 +75,21 @@ state in the Git history, by creating a new commit representing the current\n state of the <> and advancing <>\n to point at the new commit.\n \n+[[def_commit_graph_general]]commit graph concept, representations and usage::\n+\tA synonym for the <> structure formed by the commits\n+\tin the object database, <> by branch tips,\n+\tusing their <> of linked commits.\n+\tThis structure is the definitive commit graph. The\n+\tgraph can be represented in other ways, e.g. the\n+\t<>.\n+\n+[[def_commit_graph_file]]commit-graph file::\n+\tThe \"commit-graph\" (normally hyphenated) file is a supplemental\n+\trepresentation of the <>\n+\twhich accelerates commit graph walks. The \"commit-graph\" file is\n+\tstored either in the .git/objects/info directory or in the info\n+\tdirectory of an alternate object database.\n+\n [[def_commit_object]]commit object::\n \tAn <> which contains the information about a\n \tparticular <>, such as <>, committer,\n-- \n2.38.1.windows.1\n\n"},{"id":"466018","messageId":"20221029164112.2097-2-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221029164112.2097-1-philipoakley@iee.email","subject":"[PATCH v3 1/4] doc: use 'object database' not ODB or abbreviation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:41:09Z","receivedAt":"2022-10-29T16:41:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The abbreviation 'ODB' is used in the technical documentation\nsections for commit-graph and parallel-checkout, along with an\n'odb' option in `git-pack-redundant`, without expansion.\n\nUse 'object database' in full, in those entries. The text has not\nbeen reflowed to keep the changes minimal.\n\nWhile in the glossary for `object` terms, add the common`oid`\nabbreviation to its entry.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/glossary-content.txt | 2 +-\n Documentation/technical/commit-graph.txt | 2 +-\n Documentation/technical/parallel-checkout.txt | 2 +-\n 4 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex ee7034b5e5..1132c73956 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -34,7 +34,7 @@ OPTIONS\n \n --alt-odb::\n \tDon't require objects present in packs from alternate object\n-\tdirectories to be present in local packs.\n+\tdatabase (odb) directories to be present in local packs.\n \n --verbose::\n \tOutputs some statistics to stderr. Has a small performance penalty.\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex aa2f41f5e7..947ac49606 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -262,7 +262,7 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n \tidentified by its <>. The objects usually\n \tlive in `$GIT_DIR/objects/`.\n \n-[[def_object_identifier]]object identifier::\n+[[def_object_identifier]]object identifier (oid)::\n \tSynonym for <>.\n \n [[def_object_name]]object name::\ndiff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt\nindex 90c9760c23..d2a6a13650 100644\n--- a/Documentation/technical/commit-graph.txt\n+++ b/Documentation/technical/commit-graph.txt\n@@ -17,7 +17,7 @@ There are two main costs here:\n \n The commit-graph file is a supplemental data structure that accelerates\n commit graph walks. If a user downgrades or disables the 'core.commitGraph'\n-config setting, then the existing ODB is sufficient. The file is stored\n+config setting, then the existing object database is sufficient. The file is stored\n as \"commit-graph\" either in the .git/objects/info directory or in the info\n directory of an alternate.\n \ndiff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.txt\nindex e790258a1a..47c9b6183c 100644\n--- a/Documentation/technical/parallel-checkout.txt\n+++ b/Documentation/technical/parallel-checkout.txt\n@@ -56,7 +56,7 @@ Rejected Multi-Threaded Solution\n \n The most \"straightforward\" implementation would be to spread the set of\n to-be-updated cache entries across multiple threads. But due to the\n-thread-unsafe functions in the ODB code, we would have to use locks to\n+thread-unsafe functions in the object database code, we would have to use locks to\n coordinate the parallel operation. An early prototype of this solution\n showed that the multi-threaded checkout would bring performance\n improvements over the sequential code, but there was still too much lock\n-- \n2.38.1.windows.1\n\n"},{"id":"466019","messageId":"20221029164112.2097-4-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221029164112.2097-1-philipoakley@iee.email","subject":"[PATCH v3 3/4] glossary: add reachability bitmap description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:41:11Z","receivedAt":"2022-10-29T16:42:01Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Describe the purpose of the reachability bitmap.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/glossary-content.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex a526710278..5a537268e2 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -508,6 +508,14 @@ exclude;;\n \t<> to the trees or <>\n \tthat they contain.\n \n+[[def_reachability_bitmap]]reachability bitmaps::\n+\tReachability bitmaps store information about the\n+\t<> of a selected set of commits in\n+\ta packfile, or a multi-pack index (MIDX), to speed up object search.\n+\tThe bitmaps are stored in a \".bitmap\" file. A repository may have at\n+\tmost one bitmap file in use. The bitmap file may belong to either one\n+\tpack, or the repository's multi-pack index (if it exists).\n+\n [[def_rebase]]rebase::\n \tTo reapply a series of changes from a <> to a\n \tdifferent base, and reset the <> of that branch\n-- \n2.38.1.windows.1\n\n"},{"id":"466020","messageId":"20221029164112.2097-1-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221022222539.2333-1-philipoakley@iee.email","subject":"[PATCH v3 0/4] Add some Glossary of terms information","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:41:08Z","receivedAt":"2022-10-29T16:42:01Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"(in reply to <20221022222539.2333-1-philipoakley@iee.email>\n\nThis short series looks to add the basics of the reachability bitmap\nand commit graph phrases to the glossary of terms. While these\ntechniques are well known to their developers, for some, they are\njust magic phrases.\n\n[V3] .. since V2\n\n1/4 Unchanged.\n2/4 The distinction between the generic 'commit graph' of the DAG and\nthe implementation specifics of 'commit-graph' file has been retained\nfor the glossary. \nHowever the deliberate hyphenation has been included, and a fourth patch\nadded to maintain the consistency of 'commit-graph' in other documents.\n\n3/4 Tweaks & links applied to Reachability patch.\n4/4 New - maintain the consistency of 'commit-graph' in other documents.\n\n[V2] .. since V1\nwas GitGitGadget #1282,\n(in reply to )\nPatch 4/4 has been taken upstream independently, and hence dropped\nhere so we're now just [n/3].\n\nPatch 1/3 Dropped the glossary addition in favour of changing the\nlocations that used ODB (Junio's suggestion). Kept the git\npack-redundant's `--alt-odb` but spelt out 'object database' in full\nin the man page. The only remaining `odb`s are within `goodbye` ;-).\n\nWhile here, add the (oid) abbreviation to its adjacent entry.\n\nPatch 2/3 Split the 'commit-graph' explanation into two parts to\ndistinguish the speed-up option, from Git's core graph concept of\nobject traversal. Included links to existing terms.\n\nPatch 3/3 Added links to existing terms. Statement for the\nreachability bitmaps.\n\nadded cc: for Stolee (commit-graph) and Abhradeep Chakraborty\n(Bitmaps) review.\n\n\n[V1] [GGG PR #1282] \nhttps://lore.kernel.org/git/pull.1282.git.1657385781.gitgitgadget@gmail.com/\n\nThe first patch [1/4] is to show OBD as an abbreviation to avoid a UNA [0]\n\nPatch [2/4] provides a basic statement for the Commit-Graph's purpose.\n\nPatch [3/4] provides a similar statement for the reachability bitmaps.\n\nThese two patches maybe misses out on some linking information as to\nthe benefits these have and the basics of their heuristic.\n\nPatch [4/4] follows up on a bug report about the lack of idempotence\nfor the `--renormalise' command. See commit message for details.\n\n[0] UNA Un-Named Abbreviation.\n\nSigned-off-by: Philip Oakley philipoakley@iee.email\ncc: Philip Oakley philipoakley@iee.email\n\n\nPhilip Oakley (4):\n doc: use 'object database' not ODB or abbreviation\n glossary: add \"commit graph\" description\n glossary: add reachability bitmap description\n doc: use \"commit-graph\" hyphenation consistently\n\n Documentation/config/core.txt | 2 +-\n Documentation/git-pack-redundant.txt | 2 +-\n Documentation/gitformat-commit-graph.txt | 6 ++---\n Documentation/glossary-content.txt | 27 +++++++++++++++++--\n Documentation/technical/commit-graph.txt | 8 +++---\n Documentation/technical/parallel-checkout.txt | 2 +-\n 6 files changed, 35 insertions(+), 12 deletions(-)\n\nRange-diff against remotes/gitster/po/glossary-around-traversal (v2?):\n1: de164ab78b ! 1: 748b15345e doc: use 'object database' not ODB or abbreviation\n @@ Commit message\n abbreviation to its entry.\n \n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n \n ## Documentation/git-pack-redundant.txt ##\n @@ Documentation/git-pack-redundant.txt: OPTIONS\n2: f677d57699 ! 2: 052a9568e7 glossary: add \"commit graph\" description\n @@ Commit message\n glossary: add \"commit graph\" description\n \n Git has an additional \"commit graph\" capability that supplements the\n - normal commit object's directed acylic graph (DAG). The supplemental\n + normal commit object's directed acyclic graph (DAG). The supplemental\n commit graph file is designed for speed of access.\n \n Describe the commit graph both from the normative DAG view point and\n @@ Commit message\n by linking to the `ref` glossary entry, matching this commit graph\n entry.\n \n + The commit-graph file is also distinguished by its hyphenation.\n +\n + Subsequent commit catches the few cases where the hyphenation of\n + commit-graph was missing.\n +\n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n \n ## Documentation/glossary-content.txt ##\n @@\n @@ Documentation/glossary-content.txt: state in the Git history, by creating a new\n to point at the new commit.\n \n +[[def_commit_graph_general]]commit graph concept, representations and usage::\n -+\tA synonym for the <> structure formed by\n -+\tthe commits in the object database, <> by branch tips,\n ++\tA synonym for the <> structure formed by the commits\n ++\tin the object database, <> by branch tips,\n +\tusing their <> of linked commits.\n +\tThis structure is the definitive commit graph. The\n +\tgraph can be represented in other ways, e.g. the\n -+\t<>.\n ++\t<>.\n +\n -+[[def_commit_graph_file]]commit graph file::\n -+\tThe commit-graph file is a supplemental representation of\n -+\tthe <> which accelerates\n -+\tcommit graph walks. The \"commit-graph\" file is stored\n -+\teither in the .git/objects/info directory or in the info directory\n -+\tof an alternate object database.\n ++[[def_commit_graph_file]]commit-graph file::\n ++\tThe \"commit-graph\" (normally hyphenated) file is a supplemental\n ++\trepresentation of the <>\n ++\twhich accelerates commit graph walks. The \"commit-graph\" file is\n ++\tstored either in the .git/objects/info directory or in the info\n ++\tdirectory of an alternate object database.\n +\n [[def_commit_object]]commit object::\n \tAn <> which contains the information about a\n3: 39e9a282fc ! 3: d56234b70c glossary: add reachability bitmap description\n @@ Commit message\n Describe the purpose of the reachability bitmap.\n \n Signed-off-by: Philip Oakley \n - Signed-off-by: Junio C Hamano \n \n ## Documentation/glossary-content.txt ##\n @@ Documentation/glossary-content.txt: exclude;;\n @@ Documentation/glossary-content.txt: exclude;;\n \n +[[def_reachability_bitmap]]reachability bitmaps::\n +\tReachability bitmaps store information about the\n -+\t<> of a selected set of objects in\n -+\ta packfile, or a multi-pack index (MIDX) to speed up object search.\n -+\tA repository may have at\n -+\tmost one bitmap. The bitmap may belong to either one pack, or the\n -+\trepository's multi-pack index (if it exists).\n ++\t<> of a selected set of commits in\n ++\ta packfile, or a multi-pack index (MIDX), to speed up object search.\n ++\tThe bitmaps are stored in a \".bitmap\" file. A repository may have at\n ++\tmost one bitmap file in use. The bitmap file may belong to either one\n ++\tpack, or the repository's multi-pack index (if it exists).\n +\n [[def_rebase]]rebase::\n \tTo reapply a series of changes from a <> to a\n-: ---------- > 4: 87686e63f9 doc: use \"commit-graph\" hyphenation consistently\n-- \n2.38.1.windows.1\n\n"},{"id":"466021","messageId":"20221029164112.2097-5-philipoakley@iee.email","threadId":"58125","inReplyTo":"20221029164112.2097-1-philipoakley@iee.email","subject":"[PATCH v3 4/4] doc: use \"commit-graph\" hyphenation consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T16:41:12Z","receivedAt":"2022-10-29T16:42:01Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Note, historical release notes have not been updated.\n\nSigned-off-by: Philip Oakley \n\n# Conflicts:\n#\tDocumentation/gitformat-commit-graph.txt\n---\n Documentation/config/core.txt | 2 +-\n Documentation/gitformat-commit-graph.txt | 6 +++---\n Documentation/technical/commit-graph.txt | 6 +++---\n 3 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\nindex 37afbaf5a4..dfbdaf00b8 100644\n--- a/Documentation/config/core.txt\n+++ b/Documentation/config/core.txt\n@@ -618,7 +618,7 @@ but risks losing recent work in the event of an unclean system shutdown.\n * `loose-object` hardens objects added to the repo in loose-object form.\n * `pack` hardens objects added to the repo in packfile form.\n * `pack-metadata` hardens packfile bitmaps and indexes.\n-* `commit-graph` hardens the commit graph file.\n+* `commit-graph` hardens the commit-graph file.\n * `index` hardens the index when it is modified.\n * `objects` is an aggregate option that is equivalent to\n `loose-object,pack`.\ndiff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt\nindex 7324665716..31cad585e2 100644\n--- a/Documentation/gitformat-commit-graph.txt\n+++ b/Documentation/gitformat-commit-graph.txt\n@@ -3,7 +3,7 @@ gitformat-commit-graph(5)\n \n NAME\n ----\n-gitformat-commit-graph - Git commit graph format\n+gitformat-commit-graph - Git commit-graph format\n \n SYNOPSIS\n --------\n@@ -14,7 +14,7 @@ $GIT_DIR/objects/info/commit-graphs/*\n DESCRIPTION\n -----------\n \n-The Git commit graph stores a list of commit OIDs and some associated\n+The Git commit-graph stores a list of commit OIDs and some associated\n metadata, including:\n \n - The generation number of the commit.\n@@ -34,7 +34,7 @@ corresponding to the array position within the list of commit OIDs. Due\n to some special constants we use to track parents, we can store at most\n (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits.\n \n-== Commit graph files have the following format:\n+== Commit-graph files have the following format:\n \n In order to allow extensions that add extra data to the graph, we organize\n the body into \"chunks\" and provide a binary lookup table at the beginning\ndiff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt\nindex d2a6a13650..86fed0de0f 100644\n--- a/Documentation/technical/commit-graph.txt\n+++ b/Documentation/technical/commit-graph.txt\n@@ -1,4 +1,4 @@\n-Git Commit Graph Design Notes\n+Git Commit-Graph Design Notes\n =============================\n \n Git walks the commit graph for many reasons, including:\n@@ -95,7 +95,7 @@ with default order), but is not used when the topological order is\n required (such as merge base calculations, \"git log --graph\").\n \n In practice, we expect some commits to be created recently and not stored\n-in the commit graph. We can treat these commits as having \"infinite\"\n+in the commit-graph. We can treat these commits as having \"infinite\"\n generation number and walk until reaching commits with known generation\n number.\n \n@@ -149,7 +149,7 @@ Design Details\n helpful for these clones, anyway. The commit-graph will not be read or\n written when shallow commits are present.\n \n-Commit Graphs Chains\n+Commit-Graphs Chains\n --------------------\n \n Typically, repos grow with near-constant velocity (commits per day). Over time,\n-- \n2.38.1.windows.1\n\n"},{"id":"466024","messageId":"Y11hvL8Pubscz3Be@nand.local","threadId":"58125","inReplyTo":"20221029164112.2097-1-philipoakley@iee.email","subject":"Re: [PATCH v3 0/4] Add some Glossary of terms information","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2022-10-29T17:24:12Z","receivedAt":"2022-10-29T17:25:06Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Sat, Oct 29, 2022 at 05:41:08PM +0100, Philip Oakley wrote:\n> (in reply to <20221022222539.2333-1-philipoakley@iee.email>\n>\n> This short series looks to add the basics of the reachability bitmap\n> and commit graph phrases to the glossary of terms. While these\n> techniques are well known to their developers, for some, they are\n> just magic phrases.\n\nThanks, the updated round looks good to me. I applied these on top of\nthe tip of master instead of the existing merge base (which was\ndc8c8deaa6b (Prepare for 2.36.2, 2022-06-07)).\n\nWill queue.\n\nThanks,\nTaylor\n"},{"id":"466025","messageId":"24633ed6-bff9-7ece-13b5-2548b39ce6df@iee.email","threadId":"58125","inReplyTo":"Y11hvL8Pubscz3Be@nand.local","subject":"Re: [PATCH v3 0/4] Add some Glossary of terms information","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-10-29T17:34:40Z","receivedAt":"2022-10-29T17:34:52Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 29/10/2022 18:24, Taylor Blau wrote:\n> On Sat, Oct 29, 2022 at 05:41:08PM +0100, Philip Oakley wrote:\n>> (in reply to <20221022222539.2333-1-philipoakley@iee.email>\n>>\n>> This short series looks to add the basics of the reachability bitmap\n>> and commit graph phrases to the glossary of terms. While these\n>> techniques are well known to their developers, for some, they are\n>> just magic phrases.\n> Thanks, the updated round looks good to me. I applied these on top of\n> the tip of master instead of the existing merge base (which was\n> dc8c8deaa6b (Prepare for 2.36.2, 2022-06-07)).\n>\n> Will queue.\n>\n> Thanks,\n> Taylor\nThanks!\nPhilip\n"}]}