{"thread":{"id":"57719","subject":"[PATCH 1/1] documentation: guide of best practices for GIT developer","startedAt":"2022-04-12T20:42:16Z","lastAt":"2022-04-21T08:45:36Z","messageCount":17,"participants":["COGONI Guillaume","Shaoxuan Yuan","Guillaume Cogoni","Matthieu Moy","Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"453465","messageId":"20220412202557.32101-2-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"20220412202557.32101-1-cogoni.guillaume@gmail.com","subject":"[PATCH 1/1] documentation: guide of best practices for GIT developer","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-12T20:25:57Z","receivedAt":"2022-04-12T20:42:16Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"The purpose of this guide is to have a place where GIT developer can\nshare their own best practices, tools or workflows to the community in\norder to help the GIT developer.\n\nSigned-off-by: COGONI Guillaume \n---\n Documentation/Makefile | 1 +\n Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++\n 2 files changed, 54 insertions(+)\n create mode 100644 Documentation/WorkingOnGit.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44c080e3e5..82badee19a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += WorkingOnGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/WorkingOnGit.txt b/Documentation/WorkingOnGit.txt\nnew file mode 100644\nindex 0000000000..d324d9fcd8\n--- /dev/null\n+++ b/Documentation/WorkingOnGit.txt\n@@ -0,0 +1,53 @@\n+Guide of the best practices and custom workflow\n+===============================================\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This book aims to put together a lot of useful tools, best practices and\n+custom workflows that might help the Git developer.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+\n+[[debuggers]]\n+== Using debuggers\n+\n+You'll probably find it useful to use a debugger to interactively inspect\n+your code as it's running.\n+\n+There's numerous such debuggers, and you may even have one installed\n+already along with your development toolchain.\n+\n+The GNU debugger (gdb) is probably the most common one command-line\n+debugger, along with the LLDB debugger (lldb):\n+\n+==== https://www.sourceware.org/gdb/\n+==== https://lldb.llvm.org/\n+\n+=== GUIs\n+\n+==== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+In particular, this script enables using the VS Code visual debugger, including\n+setting breakpoints, logpoints, conditional breakpoints in the editor.\n+In addition, it includes the ability to see the call stack, the line of code that\n+is executing and more. It is possible to visualize the variables and their values\n+and change them during execution.\n+\n+In sum, using the built-in debugger can be particularly helpful to understand\n+how Git works internally.\n+It can be used to isolate certain parts of code, with this you may be able to ask\n+more precises question when you are stuck.\n-- \n2.25.1\n\n"},{"id":"453467","messageId":"20220412202557.32101-1-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":null,"subject":"[PATCH 0/1] documentation: guide of best practices for GIT developer","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-12T20:25:56Z","receivedAt":"2022-04-12T23:28:19Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"Hello,\n\nThis patch has for purpose to introduce a file where GIT developers can share\ntheir own best practices, tools or workflows to the community in order to\nhelp the GIT developer.\n\nThe discussion about this idea begin in this thread:\nMessage-Id: <20220407204001.112287-2-cogoni.guillaume@gmail.com>\n\nDerrick Stolee and I agreed that is can be a good idea.\nAnd, I think, it can help a newcomer, but not necessarily people with a\nlot of experience on various projects. But, we can give it a try and\nsee where it goes.\n\nPS:\nI do not believe it is a good idea to give detailed tutorials because there\nare a lot on the internet. However, give the reader pros, cons and curiosity\nto test those tools, practice or workflow can be really good.\n\nIt's better if the tools are open source and free, but it is not mandatory.\n\nSincerly,\n\nCogoni Guillaume\n\nCOGONI Guillaume (1):\n documentation: guide of best practices for GIT developer\n\n Documentation/Makefile | 1 +\n Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++\n 2 files changed, 54 insertions(+)\n create mode 100644 Documentation/WorkingOnGit.txt\n\n\nbase-commit: ab1f2765f78e75ee51dface57e1071b3b7f42b09\n-- \n2.25.1\n\n"},{"id":"453481","messageId":"CAJyCBOS=xCEmX3yPduDEQfkVYUUiawQ7sYgNHi2dGe-R2W5r-g@mail.gmail.com","threadId":"57719","inReplyTo":"20220412202557.32101-1-cogoni.guillaume@gmail.com","subject":"Re: [PATCH 0/1] documentation: guide of best practices for GIT developer","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-04-13T14:36:36Z","receivedAt":"2022-04-13T14:36:54Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"On Wed, Apr 13, 2022 at 7:29 AM COGONI Guillaume\n wrote:\n>\n> Hello,\n>\n> This patch has for purpose to introduce a file where GIT developers can share\n> their own best practices, tools or workflows to the community in order to\n> help the GIT developer.\n\nWouldn't there be a possibility that this doc can degrade into a list of\npersonal taste? I think the rules that new developers *should* know have\nalready been documented in 'MyFirstContribution.txt' or 'SubmittingPatches'\nand things like that. If there is a *common* recommended practice, if not\n\"their own\", I guess it can be added into existing documentations.\n\n> The discussion about this idea begin in this thread:\n> Message-Id: <20220407204001.112287-2-cogoni.guillaume@gmail.com>\n>\n> Derrick Stolee and I agreed that is can be a good idea.\n> And, I think, it can help a newcomer, but not necessarily people with a\n> lot of experience on various projects. But, we can give it a try and\n> see where it goes.\n>\n> PS:\n> I do not believe it is a good idea to give detailed tutorials because there\n> are a lot on the internet. However, give the reader pros, cons and curiosity\n> to test those tools, practice or workflow can be really good.\n\nThe tools that people use can vary in an incredible way, thus the workflow\ndefined by multiple tools can go even further. I think a workflow here is highly\nopinionated, and such a thing may disturb newcomers?\n\nWouldn't it be better to let people decide on their own tools and Git\nshould stay\nrespectful? Let alone most people come into the community as developer, if they\nare going to be \"WorkingOnGit\", so they may already be well-suited in their own\nworkflow?\n\n-- \nThanks & Regards,\nShaoxuan\n"},{"id":"453500","messageId":"CAA0Qn1tZxGR0cUi2JSJtTFYe2Nk9xoGuHkruji1-53-Fhokmig@mail.gmail.com","threadId":"57719","inReplyTo":"CAJyCBOS=xCEmX3yPduDEQfkVYUUiawQ7sYgNHi2dGe-R2W5r-g@mail.gmail.com","subject":"Re: [PATCH 0/1] documentation: guide of best practices for GIT developer","fromName":"Guillaume Cogoni","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-13T16:36:42Z","receivedAt":"2022-04-13T16:36:57Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"On Wed, Apr 13, 2022 at 4:36 PM Shaoxuan Yuan\n wrote:\n\n> Wouldn't there be a possibility that this doc can degrade into a list of\n> personal taste?\n\nOf course, it could end like this, if someone writes something in this\ndocument, it's because that person likes it. People are not going to\nrecommend something they don't use. But, I also think that it's not\nreally bad because the purpose it's to have a bunch of tools that\nmight interest others.\n\n> The tools that people use can vary in an incredible way, thus the workflow\n> defined by multiple tools can go even further. I think a workflow here is highly\n> opinionated, and such a thing may disturb newcomers?\n\nYup, you got a point, it's a bit complicated to recommend a workflow\nbecause there is a lot of variety. But, about tools, it's possible\nbecause you just say how this tool can be useful for the project. In\nmy first recommendation I propose the built-in debugger of VS Code and\nsay that \"It can be used to isolate certain parts of code, with this\nyou may be able to ask more precise questions when you are stuck.\". I\nthink that recommendation may not disturb newcomers or other Git\ndevelopers because it's only a tip, use the tool or not, you have the\nchoice.\n\n> Wouldn't it be better to let people decide on their own tools and Git\n> should stay respectful?\n\nIt's just a tool recommendation, and I don't force anyone to use it.\nIs it the name of the file \"WorkingOnGit\" that makes you think it's a\nmandatory thing? Maybe \"HelpToolForGit\" is better?\n\n> Let alone most people come into the community as\n> developer, if they are going to be \"WorkingOnGit\", so they may already be\n> well-suited in their own workflow?\n\nYes, naturally, but even if people have their own workflow with this\ntool or this tool, maybe if you recommend a tool that is \"better\" for\nworking on Git, will they change their habits? But, as I said it's\njust a recommendation, the final choice of whether to use it or not,\nis up to them.\n\nThanks, I appreciate your answer and I hope I've answered your questions.\nI think simply recommending tools is a good thing, because, as you\nmentioned, recommending a workflow is complicated.\n\nSIncerely,\n\nCOGONI Guillaume\n"},{"id":"453767","messageId":"20220416123433.28391-1-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"CAA0Qn1tZxGR0cUi2JSJtTFYe2Nk9xoGuHkruji1-53-Fhokmig@mail.gmail.com","subject":"[PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-16T12:34:32Z","receivedAt":"2022-04-16T12:34:54Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"I decide to change my approach with this patch, and now I agreed at some \npoint with , GIT might not be the right place \nto talk about recommendation for best practice, tools or workflows. \nSo, I change the file, it just gathers some links that point to tools \nthat have a README or scripts in contrib/.\n\nNow, the idea is more like \"Oh, you use this tool? Did you know that we\nhave a README and some scripts to make it more simple to use along GIT,\nit might interest you.\" (e.g. see contrib/emacs.). It's just informative\nand no longer a recommendation.\n\nIn addition, having a file that collects this type of information is more\npractical that have a tool mention in many files. And I hope that people \nwho use other tools other than Emacs or Visual Studio Code, will be \ninteresting for doing scripts and README in contrib/.\n\nThanks and I hope this new approach is better,\n\nCOGONI Guillaume\n\nDesmoniak (1):\n Documentation/ToolsOnGit.txt: gather information\n\n Documentation/Makefile | 1 +\n Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++\n 2 files changed, 36 insertions(+)\n create mode 100644 Documentation/ToolsOnGit.txt\n\nDifference between v0 and v1\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 82badee19a..2fd73078f7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,7 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n-TECH_DOCS += WorkingOnGit\n+TECH_DOCS += ToolsOnGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsOnGit.txt\nnew file mode 100644\nindex 0000000000..a33b369a06\n--- /dev/null\n+++ b/Documentation/ToolsOnGit.txt\n@@ -0,0 +1,35 @@\n+Tools on GIT\n+============\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This document aims to gather tools that have a README and/or scripts in\n+the GIT project.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+- <>\n+\n+[[vscode]]\n+=== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+In particular, this script enables using the VS Code visual debugger, including\n+setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n+\n+[[emacs]]\n+=== Emacs\n+\n+See contrib/emacs/README for more information.\n\ndiff --git a/Documentation/WorkingOnGit.txt b/Documentation/WorkingOnGit.txt\ndeleted file mode 100644\nindex d324d9fcd8..0000000000\n--- a/Documentation/WorkingOnGit.txt\n+++ /dev/null\n@@ -1,53 +0,0 @@\n-Guide of the best practices and custom workflow\n-===============================================\n-:sectanchors:\n-\n-[[summary]]\n-== Summary\n-\n-This book aims to put together a lot of useful tools, best practices and\n-custom workflows that might help the Git developer.\n-\n-[[author]]\n-=== Author\n-\n-The Git community.\n-\n-[[table_of_contents]]\n-== Table of contents\n-\n-- <>\n-\n-[[debuggers]]\n-== Using debuggers\n-\n-You'll probably find it useful to use a debugger to interactively inspect\n-your code as it's running.\n-\n-There's numerous such debuggers, and you may even have one installed\n-already along with your development toolchain.\n-\n-The GNU debugger (gdb) is probably the most common one command-line\n-debugger, along with the LLDB debugger (lldb):\n-\n-==== https://www.sourceware.org/gdb/\n-==== https://lldb.llvm.org/\n-\n-=== GUIs\n-\n-==== Visual Studio Code (VS Code)\n-\n-The contrib/vscode/init.sh script creates configuration files that enable\n-several valuable VS Code features. See contrib/vscode/README.md for more\n-information on using the script.\n-\n-In particular, this script enables using the VS Code visual debugger, including\n-setting breakpoints, logpoints, conditional breakpoints in the editor.\n-In addition, it includes the ability to see the call stack, the line of code that\n-is executing and more. It is possible to visualize the variables and their values\n-and change them during execution.\n-\n-In sum, using the built-in debugger can be particularly helpful to understand\n-how Git works internally.\n-It can be used to isolate certain parts of code, with this you may be able to ask\n-more precises question when you are stuck.\n\n2.25.1\n\n"},{"id":"453768","messageId":"20220416123433.28391-2-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"20220416123433.28391-1-cogoni.guillaume@gmail.com","subject":"[PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-16T12:34:33Z","receivedAt":"2022-04-16T12:34:59Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"This document aims to gather tools that have a README and/or scripts in\nthe GIT project in order to simplify the search of information for a\nparticular tool.\n\nSigned-off-by: COGONI Guillaume \n---\n Documentation/Makefile | 1 +\n Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++\n 2 files changed, 36 insertions(+)\n create mode 100644 Documentation/ToolsOnGit.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44c080e3e5..2fd73078f7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += ToolsOnGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsOnGit.txt\nnew file mode 100644\nindex 0000000000..a33b369a06\n--- /dev/null\n+++ b/Documentation/ToolsOnGit.txt\n@@ -0,0 +1,35 @@\n+Tools on GIT\n+============\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This document aims to gather tools that have a README and/or scripts in\n+the GIT project.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+- <>\n+\n+[[vscode]]\n+=== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+In particular, this script enables using the VS Code visual debugger, including\n+setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n+\n+[[emacs]]\n+=== Emacs\n+\n+See contrib/emacs/README for more information.\n-- \n2.25.1\n\n"},{"id":"453771","messageId":"0f8dbbd6-4d7b-4530-ec85-2eddfcdc9825@univ-lyon1.fr","threadId":"57719","inReplyTo":"63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr","subject":"Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@univ-lyon1.fr","sentAt":"2022-04-16T13:25:39Z","receivedAt":"2022-04-16T13:25:47Z","isPatch":true,"sender":{"key":"matthieu.moy@univ-lyon1.fr","avatar":"https://gravatar.com/avatar/8ab83b763226bd297b59ddd1463a8bfc852924577191233f73a953b86888fe0c?d=mp&s=160"},"body":"On 4/16/22 14:34, COGONI Guillaume wrote:\n> This document aims to gather tools that have a README and/or scripts in\n> the GIT project\n\nWe usually spell the project name as Git, and the command name as git. \nAnd nothing as GIT ;-).\n\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n> TECH_DOCS += MyFirstContribution\n> TECH_DOCS += MyFirstObjectWalk\n> TECH_DOCS += SubmittingPatches\n> +TECH_DOCS += ToolsOnGit\n\nIf the goal is to document tools that can be used to develop Git itself, \nprobably ToolsForGit would be more appropriate...\n\n> --- /dev/null\n> +++ b/Documentation/ToolsOnGit.txt\n> @@ -0,0 +1,35 @@\n> +Tools on GIT\n> +============\n\n... and \"Tools for developing Git\" a better long title?\n\n> +== Summary\n> +\n> +This document aims to gather tools that have a README and/or scripts in > +the GIT project.\n\nI don't think having a README should be the criterion here. To me the \ncriterion should be \"tools that may not work out of the box, but for \nwhich some explanation, configuration or script allow using the tool \nproperly\".\n\n> +[[author]]\n> +=== Author\n> +\n> +The Git community.\n> +\n> +[[table_of_contents]]\n> +== Table of contents\n> +\n> +- <>\n> +- <>\n> +\n> +[[vscode]]\n> +=== Visual Studio Code (VS Code)\n> +\n> +The contrib/vscode/init.sh script creates configuration files that enable\n> +several valuable VS Code features. See contrib/vscode/README.md for more\n> +information on using the script.\n> +\n> +In particular, this script enables using the VS Code visual debugger, including\n> +setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n\nI don't think the last sentence is needed, and if it is, it would be \nbetter within contrib/vscode/README.md (so that someone reaching this \nREADME directly do see the information too).\n\n> +[[emacs]]\n> +=== Emacs\n> +\n> +See contrib/emacs/README for more information.\n\nThis README starts with \"This directory used to contain ...\" (note the \n\"used to\". There's no reason to point the user to obsolete scripts.\n\nAlso, the stuff that used to be in this directory do not fall in the \nsame category. They were targeted at users of both Git and Emacs, but \nnot specifically to develop Git itself.\n\nOTOH, CodingGuidelines's suggestion to configure Emacs like this is IMHO \ntypically something that could appear in this document:\n\n - For Emacs, it's useful to put the following in\n GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n\n ;; note the first part is useful for C editing, too\n ((nil . ((indent-tabs-mode . t)\n (tab-width . 8)\n (fill-column . 80)))\n (cperl-mode . ((cperl-indent-level . 8)\n (cperl-extra-newline-before-brace . nil)\n (cperl-merge-trailing-else . t))))\n\nActually, the Linux kernel's CodingStyle contains more relevant stuff \n(for C, not Perl):\n\n \nhttps://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n\n(But aren't all Git devs former kernel developers? ;-) )\n\nCheers,\n\n-- \nMatthieu Moy\nhttps://matthieu-moy.fr/\n"},{"id":"453776","messageId":"0ddf91f4-2ea7-e77f-7342-38e4dd379286@iee.email","threadId":"57719","inReplyTo":"0f8dbbd6-4d7b-4530-ec85-2eddfcdc9825@univ-lyon1.fr","subject":"Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-04-16T14:51:44Z","receivedAt":"2022-04-16T14:51:53Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 16/04/2022 14:25, Matthieu Moy wrote:\n>\n>> +== Summary\n>> +\n>> +This document aims to gather tools that have a README and/or scripts\n>> in > +the GIT project.\n>\n> I don't think having a README should be the criterion here. To me the\n> criterion should be \"tools that may not work out of the box, but for\n> which some explanation, configuration or script allow using the tool\n> properly\".\n\nI'm of the view that a README is a positive indicator that there is some\ninformational value regarding the tool's use for developing Git being\nmade available. It doesn't always have to be code before it is of\nassistance in developing Git.\n\nJust my £0.02.\n--\nPhilip\n"},{"id":"453779","messageId":"xmqqlew554ye.fsf@gitster.g","threadId":"57719","inReplyTo":"0f8dbbd6-4d7b-4530-ec85-2eddfcdc9825@univ-lyon1.fr","subject":"Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-16T17:11:05Z","receivedAt":"2022-04-16T17:11:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Actually, the Linux kernel's CodingStyle contains more relevant stuff\n> (for C, not Perl):\n\nTrue.\n\n> https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n>\n> (But aren't all Git devs former kernel developers? ;-) )\n\nIt's 2022, Matthieu, not 2005 ;-).\n\nThanks for a helpful and useful review.\n\n"},{"id":"453791","messageId":"20220417093549.101436-1-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"xmqqlew554ye.fsf@gitster.g","subject":"[PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-17T09:35:48Z","receivedAt":"2022-04-17T09:36:04Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"MOY Matthieu wrote:\n\n> I don't think the last sentence is needed, and if it is, it would be\n> better within contrib/vscode/README.md (so that someone reaching this\n> README directly do see the information too).\n\nI think so too. However, I already make a PATCH last week for \ncontrib/vscode/README:\n(see <20220407204001.112287-2-cogoni.guillaume@gmail.com>).\nAnd, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14)\nit will be merge in Next. So, do I take this PATCH from the last week\nand I add it this part in contrib/vscode/README or I just add this part\nhere in this new PATCH but where the subject is different?\n\n> - For Emacs, it's useful to put the following in\n> GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n\n> ;; note the first part is useful for C editing, too\n> ((nil . ((indent-tabs-mode . t)\n> (tab-width . 8)\n> (fill-column . 80)))\n> (cperl-mode . ((cperl-indent-level . 8)\n> (cperl-extra-newline-before-brace . nil)\n> (cperl-merge-trailing-else . t))))\n\n> Actually, the Linux kernel's CodingStyle contains more relevant stuff \n> (for C, not Perl):\n\n> https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n\nI add this part directly in ToolsForGit.txt and not in the README in contrib/emacs.\nBut, from this document in Documentation/RelNotes/2.18.0.txt, I read this:\n\"The scripts in contrib/emacs/ have outlived their usefulness and have been\nreplaced with a stub that errors out and tells the user there are replacements.\"\nSo, for the next version of this PATCH, can I replace what is in the README by the \nconfiguration that I write in ToolsForGit.txt?\n\n\nOAKLEY Philip wrote:\n\n> I'm of the view that a README is a positive indicator that there is some\n> informational value regarding the tool's use for developing Git being\n> made available. It doesn't always have to be code before it is of\n> assistance in developing Git.\n\nI agreed with OAKLEY, the README is good indicator to say that we have some\ninformation besides the scripts.\n\n\nCOGONI Guillaume (1):\n Documentation/ToolsForGit.txt: Tools for developing Git\n\n Documentation/CodingGuidelines | 11 -----\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++\n 3 files changed, 80 insertions(+), 11 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\nDifference between v1 and v2\ndiff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsForGit.txt\nindex a33b369a06..d96cadd09c 100644\n--- a/Documentation/ToolsOnGit.txt\n+++ b/Documentation/ToolsForGit.txt\n@@ -1,12 +1,12 @@\n-Tools on GIT\n-============\n+Tools for developing Git\n+========================\n :sectanchors:\n \n [[summary]]\n == Summary\n \n This document aims to gather tools that have a README and/or scripts in\n-the GIT project.\n+the Git project.\n \n [[author]]\n === Author\n@@ -32,4 +32,48 @@ setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n [[emacs]]\n === Emacs\n \n-See contrib/emacs/README for more information.\n+- To follow rules of the CodingGuideline, it's useful to put the following in\n+GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n+----\n+;; note the first part is useful for C editing, too\n+((nil . ((indent-tabs-mode . t)\n+\t (tab-width . 8)\n+\t (fill-column . 80)))\n+\t (cperl-mode . ((cperl-indent-level . 8)\n+\t\t\t(cperl-extra-newline-before-brace . nil)\n+\t\t\t(cperl-merge-trailing-else . t))))\n+----\n+\n+- The version for C:\n+----\n+(defun c-lineup-arglist-tabs-only (ignored)\n+\t\"Line up argument lists by tabs, not spaces\"\n+\t(let* ((anchor (c-langelem-pos c-syntactic-element))\n+\t (column (c-langelem-2nd-pos c-syntactic-element))\n+\t (offset (- (1+ column) anchor))\n+\t (steps (floor offset c-basic-offset)))\n+\t (* (max steps 1)\n+\t c-basic-offset)))\n+\n+(add-hook 'c-mode-common-hook\n+\t(lambda ()\n+\t\t;; Add kernel style\n+\t\t(c-add-style\n+\t\t \"linux-tabs-only\"\n+\t\t '(\"linux\" (c-offsets-alist\n+\t\t\t (arglist-cont-nonempty\n+\t\t\t c-lineup-gcc-asm-reg\n+\t\t\t c-lineup-arglist-tabs-only))))))\n+\n+(add-hook 'c-mode-hook\n+\t(lambda ()\n+\t\t(let ((filename (buffer-file-name)))\n+\t\t ;; Enable kernel mode for the appropriate files\n+\t\t (when (and filename\n+\t\t\t(string-match (expand-file-name \"~/src/linux-trees\")\n+\t\t\t\t filename))\n+\t\t (setq indent-tabs-mode t)\n+\t\t (setq show-trailing-whitespace t)\n+\t\t (c-set-style \"linux-tabs-only\")))))\n+----\n+\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex b20b2f94f1..a7d21d6f6b 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -492,17 +492,6 @@ For Perl programs:\n \n - Learn and use Git.pm if you need that functionality.\n \n- - For Emacs, it's useful to put the following in\n- GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n-\n- ;; note the first part is useful for C editing, too\n- ((nil . ((indent-tabs-mode . t)\n- (tab-width . 8)\n- (fill-column . 80)))\n- (cperl-mode . ((cperl-indent-level . 8)\n- (cperl-extra-newline-before-brace . nil)\n- (cperl-merge-trailing-else . t))))\n-\n For Python scripts:\n \n - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\n\n\n-- \n2.25.1\n\n"},{"id":"453792","messageId":"20220417093549.101436-2-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"20220417093549.101436-1-cogoni.guillaume@gmail.com","subject":"[PATCH v2 1/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-17T09:35:49Z","receivedAt":"2022-04-17T09:36:06Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"This document aims to gather tools that have a README and/or scripts in\nthe GIT project in order to simplify the search of information for a\nparticular tool.\n\nMove the part about Emacs configuration from CodingGuidelines to\nToolsForGit.txt because it's the purpose of the new file centralize the\ninformation about tools.\n\nSigned-off-by: COGONI Guillaume \n---\n Documentation/CodingGuidelines | 11 -----\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++\n 3 files changed, 80 insertions(+), 11 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex b20b2f94f1..a7d21d6f6b 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -492,17 +492,6 @@ For Perl programs:\n \n - Learn and use Git.pm if you need that functionality.\n \n- - For Emacs, it's useful to put the following in\n- GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n-\n- ;; note the first part is useful for C editing, too\n- ((nil . ((indent-tabs-mode . t)\n- (tab-width . 8)\n- (fill-column . 80)))\n- (cperl-mode . ((cperl-indent-level . 8)\n- (cperl-extra-newline-before-brace . nil)\n- (cperl-merge-trailing-else . t))))\n-\n For Python scripts:\n \n - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44c080e3e5..7058dd2185 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt\nnew file mode 100644\nindex 0000000000..d96cadd09c\n--- /dev/null\n+++ b/Documentation/ToolsForGit.txt\n@@ -0,0 +1,79 @@\n+Tools for developing Git\n+========================\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This document aims to gather tools that have a README and/or scripts in\n+the Git project.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+- <>\n+\n+[[vscode]]\n+=== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+In particular, this script enables using the VS Code visual debugger, including\n+setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n+\n+[[emacs]]\n+=== Emacs\n+\n+- To follow rules of the CodingGuideline, it's useful to put the following in\n+GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n+----\n+;; note the first part is useful for C editing, too\n+((nil . ((indent-tabs-mode . t)\n+\t (tab-width . 8)\n+\t (fill-column . 80)))\n+\t (cperl-mode . ((cperl-indent-level . 8)\n+\t\t\t(cperl-extra-newline-before-brace . nil)\n+\t\t\t(cperl-merge-trailing-else . t))))\n+----\n+\n+- The version for C:\n+----\n+(defun c-lineup-arglist-tabs-only (ignored)\n+\t\"Line up argument lists by tabs, not spaces\"\n+\t(let* ((anchor (c-langelem-pos c-syntactic-element))\n+\t (column (c-langelem-2nd-pos c-syntactic-element))\n+\t (offset (- (1+ column) anchor))\n+\t (steps (floor offset c-basic-offset)))\n+\t (* (max steps 1)\n+\t c-basic-offset)))\n+\n+(add-hook 'c-mode-common-hook\n+\t(lambda ()\n+\t\t;; Add kernel style\n+\t\t(c-add-style\n+\t\t \"linux-tabs-only\"\n+\t\t '(\"linux\" (c-offsets-alist\n+\t\t\t (arglist-cont-nonempty\n+\t\t\t c-lineup-gcc-asm-reg\n+\t\t\t c-lineup-arglist-tabs-only))))))\n+\n+(add-hook 'c-mode-hook\n+\t(lambda ()\n+\t\t(let ((filename (buffer-file-name)))\n+\t\t ;; Enable kernel mode for the appropriate files\n+\t\t (when (and filename\n+\t\t\t(string-match (expand-file-name \"~/src/linux-trees\")\n+\t\t\t\t filename))\n+\t\t (setq indent-tabs-mode t)\n+\t\t (setq show-trailing-whitespace t)\n+\t\t (c-set-style \"linux-tabs-only\")))))\n+----\n+\n-- \n2.25.1\n\n"},{"id":"453793","messageId":"c6b48fba-c950-bb3a-3fdb-6d420a4cdfbc@univ-lyon1.fr","threadId":"57719","inReplyTo":"33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr","subject":"Re: [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@univ-lyon1.fr","sentAt":"2022-04-17T12:25:20Z","receivedAt":"2022-04-17T12:25:28Z","isPatch":true,"sender":{"key":"matthieu.moy@univ-lyon1.fr","avatar":"https://gravatar.com/avatar/8ab83b763226bd297b59ddd1463a8bfc852924577191233f73a953b86888fe0c?d=mp&s=160"},"body":"On 4/17/22 11:35, COGONI Guillaume wrote:\n> MOY Matthieu wrote:\n> \n>>> +In particular, this script enables using the VS Code visual debugger, including\n>>> +setting breakpoints, logpoints, conditional breakpoints and more in the editor.\n>>\n>> I don't think the last sentence is needed, and if it is, it would be\n>> better within contrib/vscode/README.md (so that someone reaching this\n>> README directly do see the information too).\n> \n> I think so too. However, I already make a PATCH last week for\n> contrib/vscode/README:\n> (see <20220407204001.112287-2-cogoni.guillaume@gmail.com>).\n> And, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14)\n> it will be merge in Next. So, do I take this PATCH from the last week\n> and I add it this part in contrib/vscode/README or I just add this part\n> here in this new PATCH but where the subject is different?\n\nI think you can just drop that sentence. For someone a bit familiar with \neither VS code or any other IDE, it's no big surprise that the debugger \nintegration allows such feature. For someone not familiar with VS code, \nthe patch about to land in next already contains a link to a page \nexplaining that.\n\nIf you want to add more explanation, then I think it should be added to \ncontrib/vscode/README. You will probably want to add in next to the \nlines touched by the previous patch, hence either Junio will have to \nsolve a conflict, or you need to write your patch on top of the previous \none.\n\n>> - For Emacs, it's useful to put the following in\n>> GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n> \n>> ;; note the first part is useful for C editing, too\n>> ((nil . ((indent-tabs-mode . t)\n>> (tab-width . 8)\n>> (fill-column . 80)))\n>> (cperl-mode . ((cperl-indent-level . 8)\n>> (cperl-extra-newline-before-brace . nil)\n>> (cperl-merge-trailing-else . t))))\n> \n>> Actually, the Linux kernel's CodingStyle contains more relevant stuff\n>> (for C, not Perl):\n> \n>> https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n> \n> I add this part directly in ToolsForGit.txt and not in the README in contrib/emacs.\n> But, from this document in Documentation/RelNotes/2.18.0.txt, I read this:\n> \"The scripts in contrib/emacs/ have outlived their usefulness and have been\n> replaced with a stub that errors out and tells the user there are replacements.\"\n> So, for the next version of this PATCH, can I replace what is in the README by the\n> configuration that I write in ToolsForGit.txt?\n\ncontrib/emacs was really not meant for developers hacking on Git. Since \nit contains only pointers to obsolete stuff, we may want to just discard \nits current content and make it the place to put documentation for \npeople hacking on Git with Emacs, just like contrib/vscode/ is for VS \ncode and Git. But we probably have only a few (tens of) lines of \ndocumentation, so adding the doc directly in ToolsForGit.txt is probably \nbetter.\n\n> OAKLEY Philip wrote:\n> \n>> I'm of the view that a README is a positive indicator that there is some\n>> informational value regarding the tool's use for developing Git being\n>> made available. It doesn't always have to be code before it is of\n>> assistance in developing Git.\n> \n> I agreed with OAKLEY, the README is good indicator to say that we have some\n> information besides the scripts.\n\nA good indicator, yes. But reading only the summary ...\n> == Summary\n> \n> This document aims to gather tools that have a README and/or scripts in\n> the Git project.\n\nI have no idea whether this document's audience is \"people hacking ON \nGit's codebase\" or \"people using Git (somewhere else)\". I believe the \nfirst sentences of the document should answer \"is this document for me?\" \n(i.e. \"shall I continue reading?\"), and currently it doesn't.\n\nSaying instead something like\n\nThis documents gathers tips, scripts and configuration file to help \npeople working on Git's codebase use their favorite tools while \nfollowing Git's coding style.\n\nwould make the target audience much clearer IMHO.\n\n> +- To follow rules of the CodingGuideline, it's useful to put the following in\n> +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n> +----\n> +;; note the first part is useful for C editing, too\n> +((nil . ((indent-tabs-mode . t)\n> +\t (tab-width . 8)\n> +\t (fill-column . 80)))\n> +\t (cperl-mode . ((cperl-indent-level . 8)\n> +\t\t\t(cperl-extra-newline-before-brace . nil)\n> +\t\t\t(cperl-merge-trailing-else . t))))\n> +----\n> +\n> +- The version for C:\n\nThe version for Perl already contains some configuration applicable to C \n(indent-tabs-mode, tab-width and fill-column).\n\n> +(add-hook 'c-mode-hook\n> +\t(lambda ()\n> +\t\t(let ((filename (buffer-file-name)))\n> +\t\t ;; Enable kernel mode for the appropriate files\n> +\t\t (when (and filename\n> +\t\t\t(string-match (expand-file-name \"~/src/linux-trees\")\n\nThis works only if the user checked out Git's source code in \n~/src/linux-trees, which is unlikely ;-). I guess this path is not to be \ntaken literally (i.e. it's more clearly \"adapt the configuration to your \nactual directory layout\"), but using linux-trees here won't make it \nclear that it should be the place to Git's source code.\n\n> +\t\t\t\t filename))\n> +\t\t (setq indent-tabs-mode t)\n\nThis one is redundant with the above for example.\n\nActually, while the tips given in Linux's kernel CodingStyle are \nrelevant for us, I'm not sure copy-pasting them in Git's tree actually \nhas added value. We may as well just link to them, like\n\nFor a more complete setup, since Git's codebase uses a coding style \nsimilar to the Linux kernel's style, tips given in Linux's CodingStyle \ndocument can be applied here too.\n\n(Plus a link to the file on kernel.org)\n\nIf you copy paste here, you should cite the source and say stg like \n\"This is adapted from Linux's suggestion in its CodingStyle document\".\n\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -492,17 +492,6 @@ For Perl programs:\n> \n> - Learn and use Git.pm if you need that functionality.\n> \n> - - For Emacs, it's useful to put the following in\n> - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n> -\n\nI agree that removing Emacs-specific code from a general document is \nnice, but then you should replace it with a link to ToolsForGit.txt like \n\"Tips to make your editor follow this style can be found in \nToolsForGit.txt\" (without being specific to Emacs, that's the point of \nthe document, it also applies to VS code and may be extended in the \nfuture to other editors).\n\nCheers,\n\n-- \nMatthieu Moy\nhttps://matthieu-moy.fr/\n"},{"id":"453977","messageId":"20220420130617.41296-1-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"c6b48fba-c950-bb3a-3fdb-6d420a4cdfbc@univ-lyon1.fr","subject":"[PATCH v3 0/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-20T13:06:16Z","receivedAt":"2022-04-20T13:07:00Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"MOY Matthieu wrote:\n\n> I think you can just drop that sentence. For someone a bit familiar with \n> either VS code or any other IDE, it's no big surprise that the debugger \n> integration allows such feature. For someone not familiar with VS code, \n> the patch about to land in next already contains a link to a page \n> explaining that.\n\nFinally, I drop that sentence, I also think that the link that I put in\ncontrib/vscode/README is sufficient.\n\n> contrib/emacs was really not meant for developers hacking on Git. Since \n> it contains only pointers to obsolete stuff, we may want to just discard \n> its current content and make it the place to put documentation for \n> people hacking on Git with Emacs, just like contrib/vscode/ is for VS \n> code and Git. But we probably have only a few (tens of) lines of \n> documentation, so adding the doc directly in ToolsForGit.txt is probably \n> better.\n\nI left everything as they were. I just add the configuration lines directly \nin ToolsForGit.txt because there is not a lot of line. \nBut, in the future, if there is more line, it would be better to move all of this \nin the contrib/emacs/README.\n\n> A good indicator, yes. But reading only the summary ...\n\nI take the summary that you propose, so this not a criterion now.\n\n> I agree that removing Emacs-specific code from a general document is \n> nice, but then you should replace it with a link to ToolsForGit.txt like \n> \"Tips to make your editor follow this style can be found in \n> ToolsForGit.txt\" (without being specific to Emacs, that's the point of \n> the document, it also applies to VS code and may be extended in the \n> future to other editors).\n\nYup, I fix this, I add a mention to Documentation/ToolsForGit.txt in CodingGuideline.\nI add it at the end of the file.\n\nThanks for your review,\n\nCOGONI Guillaume.\n\nCOGONI Guillaume (1):\n Documentation/ToolsForGit.txt: Tools for developing Git\n\n Documentation/CodingGuidelines | 18 +++++-------\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++\n 3 files changed, 59 insertions(+), 11 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\nInterdiff versus v2 :\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex a7d21d6f6b..509cd89aa2 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -722,3 +722,10 @@ Writing Documentation:\n inline substituted text+ instead of `monospaced literal text`, and with\n the former, the part that should not get substituted must be\n quoted/escaped.\n+\n+\n+Documentation/ToolsForGit.txt:\n+\n+ This document collects tips, scripts, and configuration files to help\n+ contributors working with the Git codebase use their favorite tools while\n+ following the Git coding style.\ndiff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt\nindex dc370a5861..5060d0d231 100644\n--- a/Documentation/ToolsForGit.txt\n+++ b/Documentation/ToolsForGit.txt\n@@ -5,8 +5,9 @@ Tools for developing Git\n [[summary]]\n == Summary\n \n-This document aims to gather tools that have a README and/or scripts in\n-the Git project.\n+This document gathers tips, scripts and configuration file to help people\n+working on Git's codebase use their favorite tools while following Git's\n+coding style.\n \n [[author]]\n === Author\n@@ -29,6 +30,8 @@ information on using the script.\n [[emacs]]\n === Emacs\n \n+This is adapted from Linux's suggestion in its CodingStyle document:\n+\n - To follow rules of the CodingGuideline, it's useful to put the following in\n GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n ----\n@@ -41,36 +44,8 @@ GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n \t\t\t(cperl-merge-trailing-else . t))))\n ----\n \n-- The version for C:\n-----\n-(defun c-lineup-arglist-tabs-only (ignored)\n-\t\"Line up argument lists by tabs, not spaces\"\n-\t(let* ((anchor (c-langelem-pos c-syntactic-element))\n-\t (column (c-langelem-2nd-pos c-syntactic-element))\n-\t (offset (- (1+ column) anchor))\n-\t (steps (floor offset c-basic-offset)))\n-\t (* (max steps 1)\n-\t c-basic-offset)))\n-\n-(add-hook 'c-mode-common-hook\n-\t(lambda ()\n-\t\t;; Add kernel style\n-\t\t(c-add-style\n-\t\t \"linux-tabs-only\"\n-\t\t '(\"linux\" (c-offsets-alist\n-\t\t\t (arglist-cont-nonempty\n-\t\t\t c-lineup-gcc-asm-reg\n-\t\t\t c-lineup-arglist-tabs-only))))))\n-\n-(add-hook 'c-mode-hook\n-\t(lambda ()\n-\t\t(let ((filename (buffer-file-name)))\n-\t\t ;; Enable kernel mode for the appropriate files\n-\t\t (when (and filename\n-\t\t\t(string-match (expand-file-name \"~/src/linux-trees\")\n-\t\t\t\t filename))\n-\t\t (setq indent-tabs-mode t)\n-\t\t (setq show-trailing-whitespace t)\n-\t\t (c-set-style \"linux-tabs-only\")))))\n-----\n+For a more complete setup, since Git's codebase uses a coding style\n+similar to the Linux kernel's style, tips given in Linux's CodingStyle\n+document can be applied here too.\n \n+==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n-- \n2.25.1\n\n"},{"id":"453978","messageId":"20220420130617.41296-2-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"20220420130617.41296-1-cogoni.guillaume@gmail.com","subject":"[PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-20T13:06:17Z","receivedAt":"2022-04-20T13:07:10Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"This document gathers tips, scripts and configuration file to help\npeople working on Git’s codebase use their favorite tools while\nfollowing Git’s coding style.\n\nMove the part about Emacs configuration from CodingGuidelines to\nToolsForGit.txt because it's the purpose of the new file centralize the\ninformation about tools.\n\nBut, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines\nbecause there is also information about the coding style in it.\n\nHelped-by: Matthieu Moy \nSigned-off-by: COGONI Guillaume \n---\n Documentation/CodingGuidelines | 18 +++++-------\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++\n 3 files changed, 59 insertions(+), 11 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex b20b2f94f1..509cd89aa2 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -492,17 +492,6 @@ For Perl programs:\n \n - Learn and use Git.pm if you need that functionality.\n \n- - For Emacs, it's useful to put the following in\n- GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n-\n- ;; note the first part is useful for C editing, too\n- ((nil . ((indent-tabs-mode . t)\n- (tab-width . 8)\n- (fill-column . 80)))\n- (cperl-mode . ((cperl-indent-level . 8)\n- (cperl-extra-newline-before-brace . nil)\n- (cperl-merge-trailing-else . t))))\n-\n For Python scripts:\n \n - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\n@@ -733,3 +722,10 @@ Writing Documentation:\n inline substituted text+ instead of `monospaced literal text`, and with\n the former, the part that should not get substituted must be\n quoted/escaped.\n+\n+\n+Documentation/ToolsForGit.txt:\n+\n+ This document collects tips, scripts, and configuration files to help\n+ contributors working with the Git codebase use their favorite tools while\n+ following the Git coding style.\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44c080e3e5..7058dd2185 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt\nnew file mode 100644\nindex 0000000000..5060d0d231\n--- /dev/null\n+++ b/Documentation/ToolsForGit.txt\n@@ -0,0 +1,51 @@\n+Tools for developing Git\n+========================\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This document gathers tips, scripts and configuration file to help people\n+working on Git's codebase use their favorite tools while following Git's\n+coding style.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+- <>\n+\n+[[vscode]]\n+=== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+[[emacs]]\n+=== Emacs\n+\n+This is adapted from Linux's suggestion in its CodingStyle document:\n+\n+- To follow rules of the CodingGuideline, it's useful to put the following in\n+GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n+----\n+;; note the first part is useful for C editing, too\n+((nil . ((indent-tabs-mode . t)\n+\t (tab-width . 8)\n+\t (fill-column . 80)))\n+\t (cperl-mode . ((cperl-indent-level . 8)\n+\t\t\t(cperl-extra-newline-before-brace . nil)\n+\t\t\t(cperl-merge-trailing-else . t))))\n+----\n+\n+For a more complete setup, since Git's codebase uses a coding style\n+similar to the Linux kernel's style, tips given in Linux's CodingStyle\n+document can be applied here too.\n+\n+==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n-- \n2.25.1\n\n"},{"id":"454034","messageId":"xmqq35i7o3dk.fsf@gitster.g","threadId":"57719","inReplyTo":"20220420130617.41296-2-cogoni.guillaume@gmail.com","subject":"Re: [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-20T21:23:51Z","receivedAt":"2022-04-20T21:23:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"COGONI Guillaume writes:\n\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index b20b2f94f1..509cd89aa2 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -492,17 +492,6 @@ For Perl programs:\n> \n> - Learn and use Git.pm if you need that functionality.\n> \n> - - For Emacs, it's useful to put the following in\n> - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n> -\n> - ;; note the first part is useful for C editing, too\n> - ((nil . ((indent-tabs-mode . t)\n> - (tab-width . 8)\n> - (fill-column . 80)))\n> - (cperl-mode . ((cperl-indent-level . 8)\n> - (cperl-extra-newline-before-brace . nil)\n> - (cperl-merge-trailing-else . t))))\n> -\n\nMoving this out is OK as long as it is clear to readers of this\ndocument that they can refer to the other one for tool specific\ntips.\n\n> - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\n> @@ -733,3 +722,10 @@ Writing Documentation:\n> inline substituted text+ instead of `monospaced literal text`, and with\n> the former, the part that should not get substituted must be\n> quoted/escaped.\n> +\n> +\n> +Documentation/ToolsForGit.txt:\n> +\n> + This document collects tips, scripts, and configuration files to help\n> + contributors working with the Git codebase use their favorite tools while\n> + following the Git coding style.\n\nThis looks strangely out of place. The preceding \"sections\" of this\ndocument are \n\n - general coding principle\n - specific guidelines for each language.\n - how output should read\n - how error messages should read\n - how configuration variables are named\n - how documentation pages are written\n\nThe name of a single document and explanation on what is in it does\nnot make a good new entry in that existing list.\n\nIf we must mention the existence of this document in the guidelines\ndoc, I have a feeling that a better place might be near the preface\nof the second item, e.g.\n\ndiff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines\nindex 509cd89aa2..64ff734ce7 100644\n--- c/Documentation/CodingGuidelines\n+++ w/Documentation/CodingGuidelines\n@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing\n code is expected to match the style the surrounding code already\n uses (even if it doesn't match the overall style of existing code).\n \n-But if you must have a list of rules, here they are.\n+But if you must have a list of rules, here are some language\n+specific ones. Note that Documentation/ToolsForGit document\n+has a collection of tips to help you use some external tools\n+to conform to these guidelines.\n \n For shell scripts specifically (not exhaustive):\n"},{"id":"454052","messageId":"20220421084515.21236-1-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"xmqq35i7o3dk.fsf@gitster.g","subject":"[PATCH v4 0/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-21T08:45:14Z","receivedAt":"2022-04-21T08:45:27Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"Hello,\n\nThanks for your review Junio C Hamano.\n\nCOGONI Guillaume (1):\n Documentation/ToolsForGit.txt: Tools for developing Git\n\n Documentation/CodingGuidelines | 16 +++--------\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++\n 3 files changed, 56 insertions(+), 12 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\nInterdiff against v3:\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 509cd89aa2..4c756be517 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing\n code is expected to match the style the surrounding code already\n uses (even if it doesn't match the overall style of existing code).\n \n-But if you must have a list of rules, here they are.\n+But if you must have a list of rules, here are some language\n+specific ones. Note that Documentation/ToolsForGit.txt document\n+has a collection of tips to help you use some external tools\n+to conform to these guidelines.\n \n For shell scripts specifically (not exhaustive):\n \n@@ -722,10 +725,3 @@ Writing Documentation:\n inline substituted text+ instead of `monospaced literal text`, and with\n the former, the part that should not get substituted must be\n quoted/escaped.\n-\n-\n-Documentation/ToolsForGit.txt:\n-\n- This document collects tips, scripts, and configuration files to help\n- contributors working with the Git codebase use their favorite tools while\n- following the Git coding style.\n-- \n2.25.1\n\n"},{"id":"454053","messageId":"20220421084515.21236-2-cogoni.guillaume@gmail.com","threadId":"57719","inReplyTo":"20220421084515.21236-1-cogoni.guillaume@gmail.com","subject":"[PATCH v4 1/1] Documentation/ToolsForGit.txt: Tools for developing Git","fromName":"COGONI Guillaume","fromEmail":"cogoni.guillaume@gmail.com","sentAt":"2022-04-21T08:45:15Z","receivedAt":"2022-04-21T08:45:36Z","isPatch":true,"sender":{"key":"cogoni.guillaume@gmail.com","avatar":"https://avatars.githubusercontent.com/u/60919643?v=4"},"body":"This document gathers tips, scripts and configuration file to help\npeople working on Git’s codebase use their favorite tools while\nfollowing Git’s coding style.\n\nMove the part about Emacs configuration from CodingGuidelines to\nToolsForGit.txt because it's the purpose of the new file centralize the\ninformation about tools.\n\nBut, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines\nbecause there is also information about the coding style in it.\n\nHelped-by: Matthieu Moy \nHelped-by: Junio C Hamano \nSigned-off-by: COGONI Guillaume \n---\n Documentation/CodingGuidelines | 16 +++--------\n Documentation/Makefile | 1 +\n Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++\n 3 files changed, 56 insertions(+), 12 deletions(-)\n create mode 100644 Documentation/ToolsForGit.txt\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex b20b2f94f1..4c756be517 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing\n code is expected to match the style the surrounding code already\n uses (even if it doesn't match the overall style of existing code).\n \n-But if you must have a list of rules, here they are.\n+But if you must have a list of rules, here are some language\n+specific ones. Note that Documentation/ToolsForGit.txt document\n+has a collection of tips to help you use some external tools\n+to conform to these guidelines.\n \n For shell scripts specifically (not exhaustive):\n \n@@ -492,17 +495,6 @@ For Perl programs:\n \n - Learn and use Git.pm if you need that functionality.\n \n- - For Emacs, it's useful to put the following in\n- GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n-\n- ;; note the first part is useful for C editing, too\n- ((nil . ((indent-tabs-mode . t)\n- (tab-width . 8)\n- (fill-column . 80)))\n- (cperl-mode . ((cperl-indent-level . 8)\n- (cperl-extra-newline-before-brace . nil)\n- (cperl-merge-trailing-else . t))))\n-\n For Python scripts:\n \n - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44c080e3e5..7058dd2185 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS)\n TECH_DOCS += MyFirstContribution\n TECH_DOCS += MyFirstObjectWalk\n TECH_DOCS += SubmittingPatches\n+TECH_DOCS += ToolsForGit\n TECH_DOCS += technical/bundle-format\n TECH_DOCS += technical/hash-function-transition\n TECH_DOCS += technical/http-protocol\ndiff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt\nnew file mode 100644\nindex 0000000000..5060d0d231\n--- /dev/null\n+++ b/Documentation/ToolsForGit.txt\n@@ -0,0 +1,51 @@\n+Tools for developing Git\n+========================\n+:sectanchors:\n+\n+[[summary]]\n+== Summary\n+\n+This document gathers tips, scripts and configuration file to help people\n+working on Git's codebase use their favorite tools while following Git's\n+coding style.\n+\n+[[author]]\n+=== Author\n+\n+The Git community.\n+\n+[[table_of_contents]]\n+== Table of contents\n+\n+- <>\n+- <>\n+\n+[[vscode]]\n+=== Visual Studio Code (VS Code)\n+\n+The contrib/vscode/init.sh script creates configuration files that enable\n+several valuable VS Code features. See contrib/vscode/README.md for more\n+information on using the script.\n+\n+[[emacs]]\n+=== Emacs\n+\n+This is adapted from Linux's suggestion in its CodingStyle document:\n+\n+- To follow rules of the CodingGuideline, it's useful to put the following in\n+GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:\n+----\n+;; note the first part is useful for C editing, too\n+((nil . ((indent-tabs-mode . t)\n+\t (tab-width . 8)\n+\t (fill-column . 80)))\n+\t (cperl-mode . ((cperl-indent-level . 8)\n+\t\t\t(cperl-extra-newline-before-brace . nil)\n+\t\t\t(cperl-merge-trailing-else . t))))\n+----\n+\n+For a more complete setup, since Git's codebase uses a coding style\n+similar to the Linux kernel's style, tips given in Linux's CodingStyle\n+document can be applied here too.\n+\n+==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it\n-- \n2.25.1\n\n"}]}