[PATCH 0/1] documentation: guide of best practices for GIT developer

[PATCH 0/1] documentation: guide of best practices for GIT developer

[COGONI Guillaume]

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

[PATCH 1/1] documentation: guide of best practices for GIT developer

[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

Re: [PATCH 0/1] documentation: guide of best practices for GIT developer

[Shaoxuan Yuan]

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

Re: [PATCH 0/1] documentation: guide of best practices for GIT developer

[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

[PATCH v1 0/1] Documentation/ToolsOnGit.txt: gather information about tools

[COGONI Guillaume]

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

[PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools

[COGONI Guillaume]

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

Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools

[Matthieu Moy]

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/

Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools

[Philip Oakley]

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

Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools

[Junio C Hamano]

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.

[PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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

[PATCH v2 1/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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

Re: [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git

[Matthieu Moy]

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/

[PATCH v3 0/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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

[PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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

Re: [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git

[Junio C Hamano]

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):

[PATCH v4 0/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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

[PATCH v4 1/1] Documentation/ToolsForGit.txt: Tools for developing Git

[COGONI Guillaume]

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