* [PATCH 0/1] documentation: guide of best practices for GIT developer @ 2022-04-12 20:25 COGONI Guillaume 2022-04-12 20:25 ` [PATCH 1/1] " COGONI Guillaume 2022-04-13 14:36 ` [PATCH 0/1] " Shaoxuan Yuan 0 siblings, 2 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-12 20:25 UTC (permalink / raw) To: git; +Cc: Matthieu.Moy, git.jonathan.bressat, derrickstolee, guillaume.cogoni Hello, This patch has for purpose to introduce a file where GIT developers can share their own best practices, tools or workflows to the community in order to help the GIT developer. The discussion about this idea begin in this thread: Message-Id: <20220407204001.112287-2-cogoni.guillaume@gmail.com> Derrick Stolee and I agreed that is can be a good idea. And, I think, it can help a newcomer, but not necessarily people with a lot of experience on various projects. But, we can give it a try and see where it goes. PS: I do not believe it is a good idea to give detailed tutorials because there are a lot on the internet. However, give the reader pros, cons and curiosity to test those tools, practice or workflow can be really good. It's better if the tools are open source and free, but it is not mandatory. Sincerly, Cogoni Guillaume COGONI Guillaume (1): documentation: guide of best practices for GIT developer Documentation/Makefile | 1 + Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/WorkingOnGit.txt base-commit: ab1f2765f78e75ee51dface57e1071b3b7f42b09 -- 2.25.1 ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 1/1] documentation: guide of best practices for GIT developer 2022-04-12 20:25 [PATCH 0/1] documentation: guide of best practices for GIT developer COGONI Guillaume @ 2022-04-12 20:25 ` COGONI Guillaume 2022-04-13 14:36 ` [PATCH 0/1] " Shaoxuan Yuan 1 sibling, 0 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-12 20:25 UTC (permalink / raw) To: git Cc: Matthieu.Moy, git.jonathan.bressat, derrickstolee, guillaume.cogoni, COGONI Guillaume The purpose of this guide is to have a place where GIT developer can share their own best practices, tools or workflows to the community in order to help the GIT developer. Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> --- Documentation/Makefile | 1 + Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/WorkingOnGit.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 44c080e3e5..82badee19a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += WorkingOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/WorkingOnGit.txt b/Documentation/WorkingOnGit.txt new file mode 100644 index 0000000000..d324d9fcd8 --- /dev/null +++ b/Documentation/WorkingOnGit.txt @@ -0,0 +1,53 @@ +Guide of the best practices and custom workflow +=============================================== +:sectanchors: + +[[summary]] +== Summary + +This book aims to put together a lot of useful tools, best practices and +custom workflows that might help the Git developer. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<debuggers>> + +[[debuggers]] +== Using debuggers + +You'll probably find it useful to use a debugger to interactively inspect +your code as it's running. + +There's numerous such debuggers, and you may even have one installed +already along with your development toolchain. + +The GNU debugger (gdb) is probably the most common one command-line +debugger, along with the LLDB debugger (lldb): + +==== https://www.sourceware.org/gdb/ +==== https://lldb.llvm.org/ + +=== GUIs + +==== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints in the editor. +In addition, it includes the ability to see the call stack, the line of code that +is executing and more. It is possible to visualize the variables and their values +and change them during execution. + +In sum, using the built-in debugger can be particularly helpful to understand +how Git works internally. +It can be used to isolate certain parts of code, with this you may be able to ask +more precises question when you are stuck. -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 0/1] documentation: guide of best practices for GIT developer 2022-04-12 20:25 [PATCH 0/1] documentation: guide of best practices for GIT developer COGONI Guillaume 2022-04-12 20:25 ` [PATCH 1/1] " COGONI Guillaume @ 2022-04-13 14:36 ` Shaoxuan Yuan 2022-04-13 16:36 ` Guillaume Cogoni 1 sibling, 1 reply; 17+ messages in thread From: Shaoxuan Yuan @ 2022-04-13 14:36 UTC (permalink / raw) To: COGONI Guillaume Cc: git, Matthieu.Moy, git.jonathan.bressat, derrickstolee, guillaume.cogoni On Wed, Apr 13, 2022 at 7:29 AM COGONI Guillaume <cogoni.guillaume@gmail.com> wrote: > > Hello, > > This patch has for purpose to introduce a file where GIT developers can share > their own best practices, tools or workflows to the community in order to > help the GIT developer. Wouldn't there be a possibility that this doc can degrade into a list of personal taste? I think the rules that new developers *should* know have already been documented in 'MyFirstContribution.txt' or 'SubmittingPatches' and things like that. If there is a *common* recommended practice, if not "their own", I guess it can be added into existing documentations. > The discussion about this idea begin in this thread: > Message-Id: <20220407204001.112287-2-cogoni.guillaume@gmail.com> > > Derrick Stolee and I agreed that is can be a good idea. > And, I think, it can help a newcomer, but not necessarily people with a > lot of experience on various projects. But, we can give it a try and > see where it goes. > > PS: > I do not believe it is a good idea to give detailed tutorials because there > are a lot on the internet. However, give the reader pros, cons and curiosity > to test those tools, practice or workflow can be really good. The tools that people use can vary in an incredible way, thus the workflow defined by multiple tools can go even further. I think a workflow here is highly opinionated, and such a thing may disturb newcomers? Wouldn't it be better to let people decide on their own tools and Git should stay respectful? Let alone most people come into the community as developer, if they are going to be "WorkingOnGit", so they may already be well-suited in their own workflow? -- Thanks & Regards, Shaoxuan ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 0/1] documentation: guide of best practices for GIT developer 2022-04-13 14:36 ` [PATCH 0/1] " Shaoxuan Yuan @ 2022-04-13 16:36 ` Guillaume Cogoni 2022-04-16 12:34 ` [PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools COGONI Guillaume 0 siblings, 1 reply; 17+ messages in thread From: Guillaume Cogoni @ 2022-04-13 16:36 UTC (permalink / raw) To: Shaoxuan Yuan Cc: git, Matthieu Moy, Jonathan Bressat, Derrick Stolee, guillaume.cogoni On Wed, Apr 13, 2022 at 4:36 PM Shaoxuan Yuan <shaoxuan.yuan02@gmail.com> wrote: > Wouldn't there be a possibility that this doc can degrade into a list of > personal taste? Of course, it could end like this, if someone writes something in this document, it's because that person likes it. People are not going to recommend something they don't use. But, I also think that it's not really bad because the purpose it's to have a bunch of tools that might interest others. > The tools that people use can vary in an incredible way, thus the workflow > defined by multiple tools can go even further. I think a workflow here is highly > opinionated, and such a thing may disturb newcomers? Yup, you got a point, it's a bit complicated to recommend a workflow because there is a lot of variety. But, about tools, it's possible because you just say how this tool can be useful for the project. In my first recommendation I propose the built-in debugger of VS Code and say that "It can be used to isolate certain parts of code, with this you may be able to ask more precise questions when you are stuck.". I think that recommendation may not disturb newcomers or other Git developers because it's only a tip, use the tool or not, you have the choice. > Wouldn't it be better to let people decide on their own tools and Git > should stay respectful? It's just a tool recommendation, and I don't force anyone to use it. Is it the name of the file "WorkingOnGit" that makes you think it's a mandatory thing? Maybe "HelpToolForGit" is better? > Let alone most people come into the community as > developer, if they are going to be "WorkingOnGit", so they may already be > well-suited in their own workflow? Yes, naturally, but even if people have their own workflow with this tool or this tool, maybe if you recommend a tool that is "better" for working on Git, will they change their habits? But, as I said it's just a recommendation, the final choice of whether to use it or not, is up to them. Thanks, I appreciate your answer and I hope I've answered your questions. I think simply recommending tools is a good thing, because, as you mentioned, recommending a workflow is complicated. SIncerely, COGONI Guillaume ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools 2022-04-13 16:36 ` Guillaume Cogoni @ 2022-04-16 12:34 ` COGONI Guillaume 2022-04-16 12:34 ` [PATCH v1 1/1] " COGONI Guillaume [not found] ` <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr> 0 siblings, 2 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-16 12:34 UTC (permalink / raw) To: cogoni.guillaume Cc: Matthieu.Moy, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, shaoxuan.yuan02 I decide to change my approach with this patch, and now I agreed at some point with <shaoxuan.yuan02@gmail.com>, GIT might not be the right place to talk about recommendation for best practice, tools or workflows. So, I change the file, it just gathers some links that point to tools that have a README or scripts in contrib/. Now, the idea is more like "Oh, you use this tool? Did you know that we have a README and some scripts to make it more simple to use along GIT, it might interest you." (e.g. see contrib/emacs.). It's just informative and no longer a recommendation. In addition, having a file that collects this type of information is more practical that have a tool mention in many files. And I hope that people who use other tools other than Emacs or Visual Studio Code, will be interesting for doing scripts and README in contrib/. Thanks and I hope this new approach is better, COGONI Guillaume Desmoniak (1): Documentation/ToolsOnGit.txt: gather information Documentation/Makefile | 1 + Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 Documentation/ToolsOnGit.txt Difference between v0 and v1 diff --git a/Documentation/Makefile b/Documentation/Makefile index 82badee19a..2fd73078f7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,7 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches -TECH_DOCS += WorkingOnGit +TECH_DOCS += ToolsOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsOnGit.txt new file mode 100644 index 0000000000..a33b369a06 --- /dev/null +++ b/Documentation/ToolsOnGit.txt @@ -0,0 +1,35 @@ +Tools on GIT +============ +:sectanchors: + +[[summary]] +== Summary + +This document aims to gather tools that have a README and/or scripts in +the GIT project. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor. + +[[emacs]] +=== Emacs + +See contrib/emacs/README for more information. diff --git a/Documentation/WorkingOnGit.txt b/Documentation/WorkingOnGit.txt deleted file mode 100644 index d324d9fcd8..0000000000 --- a/Documentation/WorkingOnGit.txt +++ /dev/null @@ -1,53 +0,0 @@ -Guide of the best practices and custom workflow -=============================================== -:sectanchors: - -[[summary]] -== Summary - -This book aims to put together a lot of useful tools, best practices and -custom workflows that might help the Git developer. - -[[author]] -=== Author - -The Git community. - -[[table_of_contents]] -== Table of contents - -- <<debuggers>> - -[[debuggers]] -== Using debuggers - -You'll probably find it useful to use a debugger to interactively inspect -your code as it's running. - -There's numerous such debuggers, and you may even have one installed -already along with your development toolchain. - -The GNU debugger (gdb) is probably the most common one command-line -debugger, along with the LLDB debugger (lldb): - -==== https://www.sourceware.org/gdb/ -==== https://lldb.llvm.org/ - -=== GUIs - -==== Visual Studio Code (VS Code) - -The contrib/vscode/init.sh script creates configuration files that enable -several valuable VS Code features. See contrib/vscode/README.md for more -information on using the script. - -In particular, this script enables using the VS Code visual debugger, including -setting breakpoints, logpoints, conditional breakpoints in the editor. -In addition, it includes the ability to see the call stack, the line of code that -is executing and more. It is possible to visualize the variables and their values -and change them during execution. - -In sum, using the built-in debugger can be particularly helpful to understand -how Git works internally. -It can be used to isolate certain parts of code, with this you may be able to ask -more precises question when you are stuck. 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools 2022-04-16 12:34 ` [PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools COGONI Guillaume @ 2022-04-16 12:34 ` COGONI Guillaume [not found] ` <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr> 1 sibling, 0 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-16 12:34 UTC (permalink / raw) To: cogoni.guillaume Cc: Matthieu.Moy, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, shaoxuan.yuan02 This document aims to gather tools that have a README and/or scripts in the GIT project in order to simplify the search of information for a particular tool. Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> --- Documentation/Makefile | 1 + Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 Documentation/ToolsOnGit.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 44c080e3e5..2fd73078f7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsOnGit.txt new file mode 100644 index 0000000000..a33b369a06 --- /dev/null +++ b/Documentation/ToolsOnGit.txt @@ -0,0 +1,35 @@ +Tools on GIT +============ +:sectanchors: + +[[summary]] +== Summary + +This document aims to gather tools that have a README and/or scripts in +the GIT project. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor. + +[[emacs]] +=== Emacs + +See contrib/emacs/README for more information. -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
[parent not found: <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr>]
* Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools [not found] ` <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr> @ 2022-04-16 13:25 ` Matthieu Moy 2022-04-16 14:51 ` Philip Oakley 2022-04-16 17:11 ` Junio C Hamano 0 siblings, 2 replies; 17+ messages in thread From: Matthieu Moy @ 2022-04-16 13:25 UTC (permalink / raw) To: COGONI Guillaume Cc: derrickstolee@github.com, git.jonathan.bressat@gmail.com, git@vger.kernel.org, guillaume.cogoni@gmail.com, shaoxuan.yuan02@gmail.com On 4/16/22 14:34, COGONI Guillaume wrote: > This document aims to gather tools that have a README and/or scripts in > the GIT project We usually spell the project name as Git, and the command name as git. And nothing as GIT ;-). > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) > TECH_DOCS += MyFirstContribution > TECH_DOCS += MyFirstObjectWalk > TECH_DOCS += SubmittingPatches > +TECH_DOCS += ToolsOnGit If the goal is to document tools that can be used to develop Git itself, probably ToolsForGit would be more appropriate... > --- /dev/null > +++ b/Documentation/ToolsOnGit.txt > @@ -0,0 +1,35 @@ > +Tools on GIT > +============ ... and "Tools for developing Git" a better long title? > +== Summary > + > +This document aims to gather tools that have a README and/or scripts in > +the GIT project. I don't think having a README should be the criterion here. To me the criterion should be "tools that may not work out of the box, but for which some explanation, configuration or script allow using the tool properly". > +[[author]] > +=== Author > + > +The Git community. > + > +[[table_of_contents]] > +== Table of contents > + > +- <<vscode>> > +- <<emacs>> > + > +[[vscode]] > +=== Visual Studio Code (VS Code) > + > +The contrib/vscode/init.sh script creates configuration files that enable > +several valuable VS Code features. See contrib/vscode/README.md for more > +information on using the script. > + > +In particular, this script enables using the VS Code visual debugger, including > +setting breakpoints, logpoints, conditional breakpoints and more in the editor. I don't think the last sentence is needed, and if it is, it would be better within contrib/vscode/README.md (so that someone reaching this README directly do see the information too). > +[[emacs]] > +=== Emacs > + > +See contrib/emacs/README for more information. This README starts with "This directory used to contain ..." (note the "used to". There's no reason to point the user to obsolete scripts. Also, the stuff that used to be in this directory do not fall in the same category. They were targeted at users of both Git and Emacs, but not specifically to develop Git itself. OTOH, CodingGuidelines's suggestion to configure Emacs like this is IMHO typically something that could appear in this document: - For Emacs, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: ;; note the first part is useful for C editing, too ((nil . ((indent-tabs-mode . t) (tab-width . 8) (fill-column . 80))) (cperl-mode . ((cperl-indent-level . 8) (cperl-extra-newline-before-brace . nil) (cperl-merge-trailing-else . t)))) Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl): https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it (But aren't all Git devs former kernel developers? ;-) ) Cheers, -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools 2022-04-16 13:25 ` Matthieu Moy @ 2022-04-16 14:51 ` Philip Oakley 2022-04-16 17:11 ` Junio C Hamano 1 sibling, 0 replies; 17+ messages in thread From: Philip Oakley @ 2022-04-16 14:51 UTC (permalink / raw) To: Matthieu Moy, COGONI Guillaume Cc: derrickstolee@github.com, git.jonathan.bressat@gmail.com, git@vger.kernel.org, guillaume.cogoni@gmail.com, shaoxuan.yuan02@gmail.com On 16/04/2022 14:25, Matthieu Moy wrote: > >> +== Summary >> + >> +This document aims to gather tools that have a README and/or scripts >> in > +the GIT project. > > I don't think having a README should be the criterion here. To me the > criterion should be "tools that may not work out of the box, but for > which some explanation, configuration or script allow using the tool > properly". I'm of the view that a README is a positive indicator that there is some informational value regarding the tool's use for developing Git being made available. It doesn't always have to be code before it is of assistance in developing Git. Just my £0.02. -- Philip ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools 2022-04-16 13:25 ` Matthieu Moy 2022-04-16 14:51 ` Philip Oakley @ 2022-04-16 17:11 ` Junio C Hamano 2022-04-17 9:35 ` [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git COGONI Guillaume [not found] ` <33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr> 1 sibling, 2 replies; 17+ messages in thread From: Junio C Hamano @ 2022-04-16 17:11 UTC (permalink / raw) To: Matthieu Moy Cc: COGONI Guillaume, derrickstolee@github.com, git.jonathan.bressat@gmail.com, git@vger.kernel.org, guillaume.cogoni@gmail.com, shaoxuan.yuan02@gmail.com Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> writes: > Actually, the Linux kernel's CodingStyle contains more relevant stuff > (for C, not Perl): True. > https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it > > (But aren't all Git devs former kernel developers? ;-) ) It's 2022, Matthieu, not 2005 ;-). Thanks for a helpful and useful review. ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-16 17:11 ` Junio C Hamano @ 2022-04-17 9:35 ` COGONI Guillaume 2022-04-17 9:35 ` [PATCH v2 1/1] " COGONI Guillaume [not found] ` <33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr> 1 sibling, 1 reply; 17+ messages in thread From: COGONI Guillaume @ 2022-04-17 9:35 UTC (permalink / raw) To: gitster Cc: Matthieu.Moy, cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, shaoxuan.yuan02 MOY Matthieu wrote: > I don't think the last sentence is needed, and if it is, it would be > better within contrib/vscode/README.md (so that someone reaching this > README directly do see the information too). I think so too. However, I already make a PATCH last week for contrib/vscode/README: (see <20220407204001.112287-2-cogoni.guillaume@gmail.com>). And, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14) it will be merge in Next. So, do I take this PATCH from the last week and I add it this part in contrib/vscode/README or I just add this part here in this new PATCH but where the subject is different? > - For Emacs, it's useful to put the following in > GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: > ;; note the first part is useful for C editing, too > ((nil . ((indent-tabs-mode . t) > (tab-width . 8) > (fill-column . 80))) > (cperl-mode . ((cperl-indent-level . 8) > (cperl-extra-newline-before-brace . nil) > (cperl-merge-trailing-else . t)))) > Actually, the Linux kernel's CodingStyle contains more relevant stuff > (for C, not Perl): > https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it I add this part directly in ToolsForGit.txt and not in the README in contrib/emacs. But, from this document in Documentation/RelNotes/2.18.0.txt, I read this: "The scripts in contrib/emacs/ have outlived their usefulness and have been replaced with a stub that errors out and tells the user there are replacements." So, for the next version of this PATCH, can I replace what is in the README by the configuration that I write in ToolsForGit.txt? OAKLEY Philip wrote: > I'm of the view that a README is a positive indicator that there is some > informational value regarding the tool's use for developing Git being > made available. It doesn't always have to be code before it is of > assistance in developing Git. I agreed with OAKLEY, the README is good indicator to say that we have some information besides the scripts. COGONI Guillaume (1): Documentation/ToolsForGit.txt: Tools for developing Git Documentation/CodingGuidelines | 11 ----- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt Difference between v1 and v2 diff --git a/Documentation/ToolsOnGit.txt b/Documentation/ToolsForGit.txt index a33b369a06..d96cadd09c 100644 --- a/Documentation/ToolsOnGit.txt +++ b/Documentation/ToolsForGit.txt @@ -1,12 +1,12 @@ -Tools on GIT -============ +Tools for developing Git +======================== :sectanchors: [[summary]] == Summary This document aims to gather tools that have a README and/or scripts in -the GIT project. +the Git project. [[author]] === Author @@ -32,4 +32,48 @@ setting breakpoints, logpoints, conditional breakpoints and more in the editor. [[emacs]] === Emacs -See contrib/emacs/README for more information. +- To follow rules of the CodingGuideline, it's useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +- The version for C: +---- +(defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + +(add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + +(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) +---- + diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b20b2f94f1..a7d21d6f6b 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v2 1/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-17 9:35 ` [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git COGONI Guillaume @ 2022-04-17 9:35 ` COGONI Guillaume 0 siblings, 0 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-17 9:35 UTC (permalink / raw) To: gitster Cc: Matthieu.Moy, cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, shaoxuan.yuan02 This document aims to gather tools that have a README and/or scripts in the GIT project in order to simplify the search of information for a particular tool. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> --- Documentation/CodingGuidelines | 11 ----- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b20b2f94f1..a7d21d6f6b 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). diff --git a/Documentation/Makefile b/Documentation/Makefile index 44c080e3e5..7058dd2185 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt new file mode 100644 index 0000000000..d96cadd09c --- /dev/null +++ b/Documentation/ToolsForGit.txt @@ -0,0 +1,79 @@ +Tools for developing Git +======================== +:sectanchors: + +[[summary]] +== Summary + +This document aims to gather tools that have a README and/or scripts in +the Git project. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor. + +[[emacs]] +=== Emacs + +- To follow rules of the CodingGuideline, it's useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +- The version for C: +---- +(defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + +(add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + +(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) +---- + -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
[parent not found: <33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr>]
* Re: [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git [not found] ` <33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr> @ 2022-04-17 12:25 ` Matthieu Moy 2022-04-20 13:06 ` [PATCH v3 " COGONI Guillaume 0 siblings, 1 reply; 17+ messages in thread From: Matthieu Moy @ 2022-04-17 12:25 UTC (permalink / raw) To: COGONI Guillaume, gitster@pobox.com Cc: derrickstolee@github.com, git.jonathan.bressat@gmail.com, git@vger.kernel.org, guillaume.cogoni@gmail.com, shaoxuan.yuan02@gmail.com On 4/17/22 11:35, COGONI Guillaume wrote: > MOY Matthieu wrote: > >>> +In particular, this script enables using the VS Code visual debugger, including >>> +setting breakpoints, logpoints, conditional breakpoints and more in the editor. >> >> I don't think the last sentence is needed, and if it is, it would be >> better within contrib/vscode/README.md (so that someone reaching this >> README directly do see the information too). > > I think so too. However, I already make a PATCH last week for > contrib/vscode/README: > (see <20220407204001.112287-2-cogoni.guillaume@gmail.com>). > And, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14) > it will be merge in Next. So, do I take this PATCH from the last week > and I add it this part in contrib/vscode/README or I just add this part > here in this new PATCH but where the subject is different? I think you can just drop that sentence. For someone a bit familiar with either VS code or any other IDE, it's no big surprise that the debugger integration allows such feature. For someone not familiar with VS code, the patch about to land in next already contains a link to a page explaining that. If you want to add more explanation, then I think it should be added to contrib/vscode/README. You will probably want to add in next to the lines touched by the previous patch, hence either Junio will have to solve a conflict, or you need to write your patch on top of the previous one. >> - For Emacs, it's useful to put the following in >> GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: > >> ;; note the first part is useful for C editing, too >> ((nil . ((indent-tabs-mode . t) >> (tab-width . 8) >> (fill-column . 80))) >> (cperl-mode . ((cperl-indent-level . 8) >> (cperl-extra-newline-before-brace . nil) >> (cperl-merge-trailing-else . t)))) > >> Actually, the Linux kernel's CodingStyle contains more relevant stuff >> (for C, not Perl): > >> https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it > > I add this part directly in ToolsForGit.txt and not in the README in contrib/emacs. > But, from this document in Documentation/RelNotes/2.18.0.txt, I read this: > "The scripts in contrib/emacs/ have outlived their usefulness and have been > replaced with a stub that errors out and tells the user there are replacements." > So, for the next version of this PATCH, can I replace what is in the README by the > configuration that I write in ToolsForGit.txt? contrib/emacs was really not meant for developers hacking on Git. Since it contains only pointers to obsolete stuff, we may want to just discard its current content and make it the place to put documentation for people hacking on Git with Emacs, just like contrib/vscode/ is for VS code and Git. But we probably have only a few (tens of) lines of documentation, so adding the doc directly in ToolsForGit.txt is probably better. > OAKLEY Philip wrote: > >> I'm of the view that a README is a positive indicator that there is some >> informational value regarding the tool's use for developing Git being >> made available. It doesn't always have to be code before it is of >> assistance in developing Git. > > I agreed with OAKLEY, the README is good indicator to say that we have some > information besides the scripts. A good indicator, yes. But reading only the summary ... > == Summary > > This document aims to gather tools that have a README and/or scripts in > the Git project. I have no idea whether this document's audience is "people hacking ON Git's codebase" or "people using Git (somewhere else)". I believe the first sentences of the document should answer "is this document for me?" (i.e. "shall I continue reading?"), and currently it doesn't. Saying instead something like This documents gathers tips, scripts and configuration file to help people working on Git's codebase use their favorite tools while following Git's coding style. would make the target audience much clearer IMHO. > +- To follow rules of the CodingGuideline, it's useful to put the following in > +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: > +---- > +;; note the first part is useful for C editing, too > +((nil . ((indent-tabs-mode . t) > + (tab-width . 8) > + (fill-column . 80))) > + (cperl-mode . ((cperl-indent-level . 8) > + (cperl-extra-newline-before-brace . nil) > + (cperl-merge-trailing-else . t)))) > +---- > + > +- The version for C: The version for Perl already contains some configuration applicable to C (indent-tabs-mode, tab-width and fill-column). > +(add-hook 'c-mode-hook > + (lambda () > + (let ((filename (buffer-file-name))) > + ;; Enable kernel mode for the appropriate files > + (when (and filename > + (string-match (expand-file-name "~/src/linux-trees") This works only if the user checked out Git's source code in ~/src/linux-trees, which is unlikely ;-). I guess this path is not to be taken literally (i.e. it's more clearly "adapt the configuration to your actual directory layout"), but using linux-trees here won't make it clear that it should be the place to Git's source code. > + filename)) > + (setq indent-tabs-mode t) This one is redundant with the above for example. Actually, while the tips given in Linux's kernel CodingStyle are relevant for us, I'm not sure copy-pasting them in Git's tree actually has added value. We may as well just link to them, like For a more complete setup, since Git's codebase uses a coding style similar to the Linux kernel's style, tips given in Linux's CodingStyle document can be applied here too. (Plus a link to the file on kernel.org) If you copy paste here, you should cite the source and say stg like "This is adapted from Linux's suggestion in its CodingStyle document". > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -492,17 +492,6 @@ For Perl programs: > > - Learn and use Git.pm if you need that functionality. > > - - For Emacs, it's useful to put the following in > - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: > - I agree that removing Emacs-specific code from a general document is nice, but then you should replace it with a link to ToolsForGit.txt like "Tips to make your editor follow this style can be found in ToolsForGit.txt" (without being specific to Emacs, that's the point of the document, it also applies to VS code and may be extended in the future to other editors). Cheers, -- Matthieu Moy https://matthieu-moy.fr/ ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH v3 0/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-17 12:25 ` [PATCH v2 0/1] " Matthieu Moy @ 2022-04-20 13:06 ` COGONI Guillaume 2022-04-20 13:06 ` [PATCH v3 1/1] " COGONI Guillaume 0 siblings, 1 reply; 17+ messages in thread From: COGONI Guillaume @ 2022-04-20 13:06 UTC (permalink / raw) To: matthieu.moy Cc: cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, gitster, guillaume.cogoni, shaoxuan.yuan02 MOY Matthieu wrote: > I think you can just drop that sentence. For someone a bit familiar with > either VS code or any other IDE, it's no big surprise that the debugger > integration allows such feature. For someone not familiar with VS code, > the patch about to land in next already contains a link to a page > explaining that. Finally, I drop that sentence, I also think that the link that I put in contrib/vscode/README is sufficient. > contrib/emacs was really not meant for developers hacking on Git. Since > it contains only pointers to obsolete stuff, we may want to just discard > its current content and make it the place to put documentation for > people hacking on Git with Emacs, just like contrib/vscode/ is for VS > code and Git. But we probably have only a few (tens of) lines of > documentation, so adding the doc directly in ToolsForGit.txt is probably > better. I left everything as they were. I just add the configuration lines directly in ToolsForGit.txt because there is not a lot of line. But, in the future, if there is more line, it would be better to move all of this in the contrib/emacs/README. > A good indicator, yes. But reading only the summary ... I take the summary that you propose, so this not a criterion now. > I agree that removing Emacs-specific code from a general document is > nice, but then you should replace it with a link to ToolsForGit.txt like > "Tips to make your editor follow this style can be found in > ToolsForGit.txt" (without being specific to Emacs, that's the point of > the document, it also applies to VS code and may be extended in the > future to other editors). Yup, I fix this, I add a mention to Documentation/ToolsForGit.txt in CodingGuideline. I add it at the end of the file. Thanks for your review, COGONI Guillaume. COGONI Guillaume (1): Documentation/ToolsForGit.txt: Tools for developing Git Documentation/CodingGuidelines | 18 +++++------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt Interdiff versus v2 : diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a7d21d6f6b..509cd89aa2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -722,3 +722,10 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. + + +Documentation/ToolsForGit.txt: + + This document collects tips, scripts, and configuration files to help + contributors working with the Git codebase use their favorite tools while + following the Git coding style. diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt index dc370a5861..5060d0d231 100644 --- a/Documentation/ToolsForGit.txt +++ b/Documentation/ToolsForGit.txt @@ -5,8 +5,9 @@ Tools for developing Git [[summary]] == Summary -This document aims to gather tools that have a README and/or scripts in -the Git project. +This document gathers tips, scripts and configuration file to help people +working on Git's codebase use their favorite tools while following Git's +coding style. [[author]] === Author @@ -29,6 +30,8 @@ information on using the script. [[emacs]] === Emacs +This is adapted from Linux's suggestion in its CodingStyle document: + - To follow rules of the CodingGuideline, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: ---- @@ -41,36 +44,8 @@ GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: (cperl-merge-trailing-else . t)))) ---- -- The version for C: ----- -(defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - -(add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - -(add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) ----- +For a more complete setup, since Git's codebase uses a coding style +similar to the Linux kernel's style, tips given in Linux's CodingStyle +document can be applied here too. +==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-20 13:06 ` [PATCH v3 " COGONI Guillaume @ 2022-04-20 13:06 ` COGONI Guillaume 2022-04-20 21:23 ` Junio C Hamano 0 siblings, 1 reply; 17+ messages in thread From: COGONI Guillaume @ 2022-04-20 13:06 UTC (permalink / raw) To: matthieu.moy Cc: cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, gitster, guillaume.cogoni, shaoxuan.yuan02, Matthieu Moy This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it. Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> --- Documentation/CodingGuidelines | 18 +++++------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b20b2f94f1..509cd89aa2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). @@ -733,3 +722,10 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. + + +Documentation/ToolsForGit.txt: + + This document collects tips, scripts, and configuration files to help + contributors working with the Git codebase use their favorite tools while + following the Git coding style. diff --git a/Documentation/Makefile b/Documentation/Makefile index 44c080e3e5..7058dd2185 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt new file mode 100644 index 0000000000..5060d0d231 --- /dev/null +++ b/Documentation/ToolsForGit.txt @@ -0,0 +1,51 @@ +Tools for developing Git +======================== +:sectanchors: + +[[summary]] +== Summary + +This document gathers tips, scripts and configuration file to help people +working on Git's codebase use their favorite tools while following Git's +coding style. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +[[emacs]] +=== Emacs + +This is adapted from Linux's suggestion in its CodingStyle document: + +- To follow rules of the CodingGuideline, it's useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +For a more complete setup, since Git's codebase uses a coding style +similar to the Linux kernel's style, tips given in Linux's CodingStyle +document can be applied here too. + +==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-20 13:06 ` [PATCH v3 1/1] " COGONI Guillaume @ 2022-04-20 21:23 ` Junio C Hamano 2022-04-21 8:45 ` [PATCH v4 0/1] " COGONI Guillaume 0 siblings, 1 reply; 17+ messages in thread From: Junio C Hamano @ 2022-04-20 21:23 UTC (permalink / raw) To: COGONI Guillaume Cc: matthieu.moy, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, shaoxuan.yuan02 COGONI Guillaume <cogoni.guillaume@gmail.com> writes: > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index b20b2f94f1..509cd89aa2 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -492,17 +492,6 @@ For Perl programs: > > - Learn and use Git.pm if you need that functionality. > > - - For Emacs, it's useful to put the following in > - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: > - > - ;; note the first part is useful for C editing, too > - ((nil . ((indent-tabs-mode . t) > - (tab-width . 8) > - (fill-column . 80))) > - (cperl-mode . ((cperl-indent-level . 8) > - (cperl-extra-newline-before-brace . nil) > - (cperl-merge-trailing-else . t)))) > - Moving this out is OK as long as it is clear to readers of this document that they can refer to the other one for tool specific tips. > - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). > @@ -733,3 +722,10 @@ Writing Documentation: > inline substituted text+ instead of `monospaced literal text`, and with > the former, the part that should not get substituted must be > quoted/escaped. > + > + > +Documentation/ToolsForGit.txt: > + > + This document collects tips, scripts, and configuration files to help > + contributors working with the Git codebase use their favorite tools while > + following the Git coding style. This looks strangely out of place. The preceding "sections" of this document are - general coding principle - specific guidelines for each language. - how output should read - how error messages should read - how configuration variables are named - how documentation pages are written The name of a single document and explanation on what is in it does not make a good new entry in that existing list. If we must mention the existence of this document in the guidelines doc, I have a feeling that a better place might be near the preface of the second item, e.g. diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines index 509cd89aa2..64ff734ce7 100644 --- c/Documentation/CodingGuidelines +++ w/Documentation/CodingGuidelines @@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v4 0/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-20 21:23 ` Junio C Hamano @ 2022-04-21 8:45 ` COGONI Guillaume 2022-04-21 8:45 ` [PATCH v4 1/1] " COGONI Guillaume 0 siblings, 1 reply; 17+ messages in thread From: COGONI Guillaume @ 2022-04-21 8:45 UTC (permalink / raw) To: gitster Cc: cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, matthieu.moy, shaoxuan.yuan02 Hello, Thanks for your review Junio C Hamano. COGONI Guillaume (1): Documentation/ToolsForGit.txt: Tools for developing Git Documentation/CodingGuidelines | 16 +++-------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 Documentation/ToolsForGit.txt Interdiff against v3: diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 509cd89aa2..4c756be517 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): @@ -722,10 +725,3 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. - - -Documentation/ToolsForGit.txt: - - This document collects tips, scripts, and configuration files to help - contributors working with the Git codebase use their favorite tools while - following the Git coding style. -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v4 1/1] Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-21 8:45 ` [PATCH v4 0/1] " COGONI Guillaume @ 2022-04-21 8:45 ` COGONI Guillaume 0 siblings, 0 replies; 17+ messages in thread From: COGONI Guillaume @ 2022-04-21 8:45 UTC (permalink / raw) To: gitster Cc: cogoni.guillaume, derrickstolee, git.jonathan.bressat, git, guillaume.cogoni, matthieu.moy, shaoxuan.yuan02, Matthieu Moy This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it. Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> --- Documentation/CodingGuidelines | 16 +++-------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 Documentation/ToolsForGit.txt diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b20b2f94f1..4c756be517 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive): @@ -492,17 +495,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). diff --git a/Documentation/Makefile b/Documentation/Makefile index 44c080e3e5..7058dd2185 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.txt new file mode 100644 index 0000000000..5060d0d231 --- /dev/null +++ b/Documentation/ToolsForGit.txt @@ -0,0 +1,51 @@ +Tools for developing Git +======================== +:sectanchors: + +[[summary]] +== Summary + +This document gathers tips, scripts and configuration file to help people +working on Git's codebase use their favorite tools while following Git's +coding style. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +[[emacs]] +=== Emacs + +This is adapted from Linux's suggestion in its CodingStyle document: + +- To follow rules of the CodingGuideline, it's useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +For a more complete setup, since Git's codebase uses a coding style +similar to the Linux kernel's style, tips given in Linux's CodingStyle +document can be applied here too. + +==== https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it -- 2.25.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
end of thread, other threads:[~2022-04-21 8:45 UTC | newest] Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-04-12 20:25 [PATCH 0/1] documentation: guide of best practices for GIT developer COGONI Guillaume 2022-04-12 20:25 ` [PATCH 1/1] " COGONI Guillaume 2022-04-13 14:36 ` [PATCH 0/1] " Shaoxuan Yuan 2022-04-13 16:36 ` Guillaume Cogoni 2022-04-16 12:34 ` [PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools COGONI Guillaume 2022-04-16 12:34 ` [PATCH v1 1/1] " COGONI Guillaume [not found] ` <63d7dc69656e47f7bc7bce4839711f32@SAMBXP02.univ-lyon1.fr> 2022-04-16 13:25 ` Matthieu Moy 2022-04-16 14:51 ` Philip Oakley 2022-04-16 17:11 ` Junio C Hamano 2022-04-17 9:35 ` [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git COGONI Guillaume 2022-04-17 9:35 ` [PATCH v2 1/1] " COGONI Guillaume [not found] ` <33d2087c66e44037b03db818dae60fea@SAMBXP02.univ-lyon1.fr> 2022-04-17 12:25 ` [PATCH v2 0/1] " Matthieu Moy 2022-04-20 13:06 ` [PATCH v3 " COGONI Guillaume 2022-04-20 13:06 ` [PATCH v3 1/1] " COGONI Guillaume 2022-04-20 21:23 ` Junio C Hamano 2022-04-21 8:45 ` [PATCH v4 0/1] " COGONI Guillaume 2022-04-21 8:45 ` [PATCH v4 1/1] " COGONI Guillaume
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).