contrib/vscode/: debugging with vscode and gdb

contrib/vscode/: debugging with vscode and gdb

[Jonathan Bressat]

Hello
In contrib/vscode/ the script init.sh create launch.json with the
option "external console" to true but actually this option make gdb
didn't work so we passed to false and then it works.
Is there any reasons why it is set to true, do we not use this properly ?
Then would it be nice to correct it in contrib/vscode and to talk
about it in that doc : https://git-scm.com/docs/MyFirstContribution ?

Thanks,

Guillaume COGONI and
Jonathan BRESSAT

Re: contrib/vscode/: debugging with vscode and gdb

[Derrick Stolee]

On 3/24/2022 4:16 AM, Jonathan Bressat wrote:
> Hello
> In contrib/vscode/ the script init.sh create launch.json with the
> option "external console" to true but actually this option make gdb
> didn't work so we passed to false and then it works.
> Is there any reasons why it is set to true, do we not use this properly ?
> Then would it be nice to correct it in contrib/vscode and to talk
> about it in that doc : https://git-scm.com/docs/MyFirstContribution ?

Hi Jonathan and Guillaume,

I use VS Code to work on Git (using Remote SSH from a Windows machine
to a Linux machine) but I've always used command-line gdb for debugging.

However, your request here got me interested. I confirmed that running
the debugger from the VS Code UI did not show any output or show that
a breakpoint was hit. Performing the update you recommend made the
debuggin UI populate with all the necessary info (stack trace, variables,
showing the breakpoint line in the editor).

Here is a patch that makes the change as you suggest. I tried to research
the setting appropriately, so please let me know if there is anything you
think is incorrect here.

Thanks,
-Stolee

--- >8 ---

From b053b797cf8585d2b0212cd2576fe05c2d1a5432 Mon Sep 17 00:00:00 2001
From: Derrick Stolee <derrickstolee@github.com>
Date: Fri, 25 Mar 2022 09:07:11 -0400
Subject: [PATCH] contrib/vscode: fix interaction with UI debugger

The contrib/vscode/init.sh script helps Git developers using Visual
Studio Code to hook up the proper settings to work on Git using the UI
features of that editor environment. This should include the debugger
integration, but that is currently broken.

One thing this script does is create a .vscode/launch.json file, which
provides the information for how VS Code should launch the built
executable. This defaults to the Git executable at the root of the
repository (with no arguments). Among the initial settings, the
"externalConsole" setting is set to "true". This has been the case since
the script was created in 54c06c6013 (contrib: add a script to
initialize VS Code configuration, 2018-07-30).

Jonathan and Guillame reported that flipping this setting to "false"
allows the VS Code debugger to work with Git. I verified that the
debugger did not work by default but now does with this change.

The VS Code reference [1] mentions that this setting is only used when
debugging, so should not affect the "Run Without Debugging" feature.
Other than making the UI debugger work, this will also change the Git
output to appear in the "Debug Console" tab instead of a new window.

[1] https://code.visualstudio.com/docs/cpp/launch-json-reference

In cases such as using the Remote SSH capability, this setting is
necessary to have any success executing Git via the "Run" menu, since
the external console is not visible at all from the VS Code window.

Reported-by: Jonathan Bressat <git.jonathan.bressat@gmail.com>
Reported-by: Cogoni Guillaume <cogoni.guillaume@gmail.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>
---
 contrib/vscode/init.sh  |  2 +-
 t/test-lib-functions.sh | 34 ----------------------------------
 2 files changed, 1 insertion(+), 35 deletions(-)

diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b5..0b7ebc12668 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,7 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
+            "externalConsole": false,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
diff --git a/t/test-lib-functions.sh b/t/test-lib-functions.sh
index 8f0e5da8727..2501fc5706f 100644
--- a/t/test-lib-functions.sh
+++ b/t/test-lib-functions.sh
@@ -1788,40 +1788,6 @@ test_subcommand () {
 	fi
 }
 
-# Check that the given command was invoked as part of the
-# trace2-format trace on stdin, but without an exact set of
-# arguments.
-#
-#	test_subcommand [!] <command> <args>... < <trace>
-#
-# For example, to look for an invocation of "git pack-objects"
-# with the "--honor-pack-keep" argument, use
-#
-#	GIT_TRACE2_EVENT=event.log git repack ... &&
-#	test_subcommand git pack-objects --honor-pack-keep <event.log
-#
-# If the first parameter passed is !, this instead checks that
-# the given command was not called.
-#
-test_subcommand_inexact () {
-	local negate=
-	if test "$1" = "!"
-	then
-		negate=t
-		shift
-	fi
-
-	local expr=$(printf '"%s",' "$@")
-	expr="${expr%,}.*"
-
-	if test -n "$negate"
-	then
-		! grep "\"event\":\"child_start\".*\[$expr\]"
-	else
-		grep "\"event\":\"child_start\".*\[$expr\]"
-	fi
-}
-
 # Check that the given command was invoked as part of the
 # trace2-format trace on stdin.
 #
-- 
2.35.1.138.gfc5de29e9e6

Re: contrib/vscode/: debugging with vscode and gdb

[Matthieu Moy]

On 3/25/22 14:19, Derrick Stolee wrote:

> Jonathan and Guillame reported that flipping this setting to "false"
> allows the VS Code debugger to work with Git. I verified that the
> debugger did not work by default but now does with this change.

FYI, I got the same problem, and I can reproduce the issue on a hello 
world program, so "externalConsole": true, is broken at least for me 
regardless of the Git codebase.

I couldn't understand what exactly the option was supposed to do. If I 
understand correctly, it should launch another window to show the git 
program output, but I don't know which window actually (xterm? 
x-terminal-emulator? a terminal program that isn't installed on my system?).

>   contrib/vscode/init.sh  |  2 +-
>   t/test-lib-functions.sh | 34 ----------------------------------

I guess the test-lib-functions.sh part is a leftover from another work?

> -            "externalConsole": true,
> +            "externalConsole": false,
I'd actually remove the line completely, to mean "let VSCode decide what 
to do", i.e. either VSCode's default, or the user's configuration 
("launch" section in settings.json, see e.g. 
https://code.visualstudio.com/docs/getstarted/settings ). If some user 
has a non-broken externalConsole: true VSCode and likes this behavior, 
then the best place to configure it is in a user-wide config file IHMO.

Cheers,

-- 
Matthieu Moy
https://matthieu-moy.fr/

Re: contrib/vscode/: debugging with vscode and gdb

[Derrick Stolee]

On 3/25/2022 2:27 PM, Matthieu Moy wrote:
> On 3/25/22 14:19, Derrick Stolee wrote:
> 
>> Jonathan and Guillame reported that flipping this setting to "false"
>> allows the VS Code debugger to work with Git. I verified that the
>> debugger did not work by default but now does with this change.
> 
> FYI, I got the same problem, and I can reproduce the issue on a hello world program, so "externalConsole": true, is broken at least for me regardless of the Git codebase.
> 
> I couldn't understand what exactly the option was supposed to do. If I understand correctly, it should launch another window to show the git program output, but I don't know which window actually (xterm? x-terminal-emulator? a terminal program that isn't installed on my system?).
> 
>>   contrib/vscode/init.sh  |  2 +-
>>   t/test-lib-functions.sh | 34 ----------------------------------
> 
> I guess the test-lib-functions.sh part is a leftover from another work?

Whoops! Yes I was in the wrong worktree.

>> -            "externalConsole": true,
>> +            "externalConsole": false,
> I'd actually remove the line completely, to mean "let VSCode decide what to do", i.e. either VSCode's default, or the user's configuration ("launch" section in settings.json, see e.g. https://code.visualstudio.com/docs/getstarted/settings ). If some user has a non-broken externalConsole: true VSCode and likes this behavior, then the best place to configure it is in a user-wide config file IHMO.

I confirmed that deleting the line works just fine.

Here's a better patch without the bogus extra changes.

--- >8 ---

From 8d8ac565a9c6631a509f301e7719692bd781f8d2 Mon Sep 17 00:00:00 2001
From: Derrick Stolee <derrickstolee@github.com>
Date: Fri, 25 Mar 2022 09:07:11 -0400
Subject: [PATCH] contrib/vscode: fix interaction with UI debugger

The contrib/vscode/init.sh script helps Git developers using Visual
Studio Code to hook up the proper settings to work on Git using the UI
features of that editor environment. This should include the debugger
integration, but that is currently broken.

One thing this script does is create a .vscode/launch.json file, which
provides the information for how VS Code should launch the built
executable. This defaults to the Git executable at the root of the
repository (with no arguments). Among the initial settings, the
"externalConsole" setting is set to "true". This has been the case since
the script was created in 54c06c6013 (contrib: add a script to
initialize VS Code configuration, 2018-07-30).

Jonathan and Guillame reported that flipping this setting to "false"
allows the VS Code debugger to work with Git. Matthieu pointed out that
this is the default, so we can leave it out of the file completely and
let a user modify that themselves if they want. I validated that both
the "false" setting and removing the line both work.

The VS Code reference [1] mentions that this setting is only used when
debugging, so should not affect the "Run Without Debugging" feature.
Other than making the UI debugger work, this will also change the Git
output to appear in the "Debug Console" tab instead of a new window.

[1] https://code.visualstudio.com/docs/cpp/launch-json-reference

In cases such as using the Remote SSH capability, this setting is
necessary to have any success executing Git via the "Run" menu, since
the external console is not visible at all from the VS Code window.

Reported-by: Jonathan Bressat <git.jonathan.bressat@gmail.com>
Reported-by: Cogoni Guillaume <cogoni.guillaume@gmail.com>
Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>
---
 contrib/vscode/init.sh | 1 -
 1 file changed, 1 deletion(-)

diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b5..f139fd86444 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
-- 
2.35.1.138.gfc5de29e9e6

Re: contrib/vscode/: debugging with vscode and gdb

[Jonathan Bressat]

On 3/25/2022 2:27 PM, Matthieu Moy wrote:

> I couldn't understand what exactly the option was supposed to do. If I
> understand correctly, it should launch another window to show the git
> program output, but I don't know which window actually (xterm?
> x-terminal-emulator? a terminal program that isn't installed on my system?).

In VS Code settings, it seems to be x-terminal-emulator.


On 3/25/2022 8:01 PM, Derrick Stolee <derrickstolee@github.com> wrote :
> >> - "externalConsole": true,
> >> + "externalConsole": false,
> I'd actually remove the line completely, to mean "let VSCode decide what to do", i.e. either VSCode's default, or the user's configuration ("launch" section in settings.json, see e.g. https://code.visualstudio.com/docs/getstarted/settings ). If some user has a > non-broken externalConsole: true VSCode and likes this behavior, then the best place to configure it is in a user-wide config file IHMO.
>
> I confirmed that deleting the line works just fine.

Yes, we agree with both of you, remove the line completly is better
because it let the user choices his preferences.
And it also work for us.

> Reported-by: Jonathan Bressat <git.jonathan.bressat@gmail.com>
> Reported-by: Cogoni Guillaume <cogoni.guillaume@gmail.com>
> Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
> Signed-off-by: Derrick Stolee <derrickstolee@github.com>
> ---
> contrib/vscode/init.sh | 1 -
> 1 file changed, 1 deletion(-)
>
> diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
> index 27de94994b5..f139fd86444 100755
> --- a/contrib/vscode/init.sh
> +++ b/contrib/vscode/init.sh
> @@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
> "stopAtEntry": false,
> "cwd": "\${workspaceFolder}",
> "environment": [],
> - "externalConsole": true,
> "MIMode": "gdb",
> "miDebuggerPath": "$GDBPATH",
> "setupCommands": [
> --
> 2.35.1.138.gfc5de29e9e6
>
>

https://code.visualstudio.com/docs/editor/debugging
https://code.visualstudio.com/docs/getstarted/settings
Maybe, It would be nice to add these two links in
contrib/vscode/readme.md, this may be relevant to
help new users that want to use vscode debugger. And add some explanations
like "How to use it".

Except that, your patch sounds good for us.

Thanks,

Guillaume and Jonathan.

Re: contrib/vscode/: debugging with vscode and gdb

[Guillaume Cogoni]

Hello,

We don't know if we can revive this topic, but we still think that
it's a good idea
to talk more about "how it can be useful to use the debugging tool that gives
VS Code".

So, we make a patch about it.
We retrieve what Derrick Stolee did and add what we said in our previous mail.

Thanks,
Cogoni Guillaume and Jonathan Bressat

--------------------->8-----------------------------------

Subject: [PATCH 0/1] contrib/vscode/: debugging with VS Code and gdb
COGONI Guillaume (1):
contrib/vscode/: debugging with VS Code and gdb

| Documentation/MyFirstContribution.txt | 12 ++++++++++++
| contrib/vscode/README.md | 5 +++++
| contrib/vscode/init.sh | 1 -
| 3 files changed, 17 insertions(+), 1 deletion(-)

-- 
2.25.1

Date: Sun, 3 Apr 2022 21:47:02 +0200
Subject: [PATCH 1/1] contrib/vscode/: debugging with VS Code and gdb

Remove "externalConsole" line in contrib/vscode/init.sh because it
seems to not work for everyone, and after a discussion with Matthieu
Moy and Derrick Stolee, we agreed that it is better to let the user choose
what to do with this line (Add his own configuration).

Add useful links in contrib/vscode/README.md to help the user to
configure his VS Code and how to use the debugging feature.

Add a mention to the README in Documentation/MyFirstContribution.txt
and a part "To convince a newcomer that VS Code can help him".

Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Helped-by: Derrick Stolee <derrickstolee@github.com>
---
Documentation/MyFirstContribution.txt | 12 ++++++++++++
contrib/vscode/README.md | 5 +++++
contrib/vscode/init.sh | 1 -
3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/Documentation/MyFirstContribution.txt
b/Documentation/MyFirstContribution.txt
index 63a2ef5449..97f53f536d 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1265,3 +1265,15 @@ against the appropriate GitGitGadget/Git branch.
If you're using `git send-email`, you can use it the same way as before, but you
should generate your diffs from `<topic>..<mybranch>` and base your work on
`<topic>` instead of `master`.
+
+[[Bonus-useful-tools]]
+== Bonus - useful tools
+
+=== VS Code
+
+To see "how to use VS Code" read contrib/vscode/README.md.
+If you want to try to understand "how git works internally", the debugging
+feature of VS Code can help you. It will not give you all the keys to
fully understand it, but
+it can give you an idea of "how the information travels inside the code".
+It can help you to isolate some parts of code, with this you are able
+to ask more precise questions when you are stuck. (See getting-help sections).
\ No newline at end of file

diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index 8202d62035..a416a752c1 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -8,6 +8,11 @@ code editor which runs on your desktop and is available for
[Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
it has [support for C/C++ via an
extension](https://github.com/Microsoft/vscode-cpptools).
+To understand "how works the debugging part" read:
+[Help with the debugging
part](https://code.visualstudio.com/docs/editor/debugging)
+To get help about "how to personalize your settings" read:
+[How to set up your
settings](https://code.visualstudio.com/docs/getstarted/settings)
+
To start developing Git with VS Code, simply run the Unix shell script called
`init.sh` in this directory, which creates the configuration files in
`.vscode/` that VS Code consumes. `init.sh` needs access to `make` and `gcc`,

diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b..f139fd8644 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
"stopAtEntry": false,
"cwd": "\${workspaceFolder}",
"environment": [],
- "externalConsole": true,
"MIMode": "gdb",
"miDebuggerPath": "$GDBPATH",
"setupCommands": [
-- 
2.25.1

On Sat, Mar 26, 2022 at 3:11 PM Jonathan Bressat
<git.jonathan.bressat@gmail.com> wrote:
>
> On 3/25/2022 2:27 PM, Matthieu Moy wrote:
>
> > I couldn't understand what exactly the option was supposed to do. If I
> > understand correctly, it should launch another window to show the git
> > program output, but I don't know which window actually (xterm?
> > x-terminal-emulator? a terminal program that isn't installed on my system?).
>
> In VS Code settings, it seems to be x-terminal-emulator.
>
>
> On 3/25/2022 8:01 PM, Derrick Stolee <derrickstolee@github.com> wrote :
> > >> - "externalConsole": true,
> > >> + "externalConsole": false,
> > I'd actually remove the line completely, to mean "let VSCode decide what to do", i.e. either VSCode's default, or the user's configuration ("launch" section in settings.json, see e.g. https://code.visualstudio.com/docs/getstarted/settings ). If some user has a > non-broken externalConsole: true VSCode and likes this behavior, then the best place to configure it is in a user-wide config file IHMO.
> >
> > I confirmed that deleting the line works just fine.
>
> Yes, we agree with both of you, remove the line completly is better
> because it let the user choices his preferences.
> And it also work for us.
>
> > Reported-by: Jonathan Bressat <git.jonathan.bressat@gmail.com>
> > Reported-by: Cogoni Guillaume <cogoni.guillaume@gmail.com>
> > Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
> > Signed-off-by: Derrick Stolee <derrickstolee@github.com>
> > ---
> > contrib/vscode/init.sh | 1 -
> > 1 file changed, 1 deletion(-)
> >
> > diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
> > index 27de94994b5..f139fd86444 100755
> > --- a/contrib/vscode/init.sh
> > +++ b/contrib/vscode/init.sh
> > @@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
> > "stopAtEntry": false,
> > "cwd": "\${workspaceFolder}",
> > "environment": [],
> > - "externalConsole": true,
> > "MIMode": "gdb",
> > "miDebuggerPath": "$GDBPATH",
> > "setupCommands": [
> > --
> > 2.35.1.138.gfc5de29e9e6
> >
> >
>
> https://code.visualstudio.com/docs/editor/debugging
> https://code.visualstudio.com/docs/getstarted/settings
> Maybe, It would be nice to add these two links in
> contrib/vscode/readme.md, this may be relevant to
> help new users that want to use vscode debugger. And add some explanations
> like "How to use it".
>
> Except that, your patch sounds good for us.
>
> Thanks,
>
> Guillaume and Jonathan.

Re: contrib/vscode/: debugging with vscode and gdb

[Matthieu Moy]

On 4/3/22 22:18, Guillaume Cogoni wrote:
> Hello,
> 
> We don't know if we can revive this topic, but we still think that
> it's a good idea
> to talk more about "how it can be useful to use the debugging tool that gives
> VS Code".
> 
> So, we make a patch about it.
> We retrieve what Derrick Stolee did and add what we said in our previous mail.
> 
> Thanks,
> Cogoni Guillaume and Jonathan Bressat
> 
> --------------------->8-----------------------------------
> 
> Subject: [PATCH 0/1] contrib/vscode/: debugging with VS Code and gdb
> COGONI Guillaume (1):
> contrib/vscode/: debugging with VS Code and gdb

How did you generate this patch? It doesn't apply with 'git am', I 
suspect you copy-pasted incorrectly into your mailer. Using 'git 
send-email' helps sending properly formatted patches.

 > Remove "externalConsole" line in contrib/vscode/init.sh because it
 > seems to not work for everyone, and after a discussion with Matthieu
 > Moy and Derrick Stolee, we agreed that it is better to let the user 
choose
 > what to do with this line

I usually explain the problem first, and then the solution.

The externalConsole=true setting is broken for many users (launching the 
debugger with such setting results in VS Code waiting forever without 
actually starting the debugger). Also, this setting is a matter of user 
preference, and is arguably better set in a "launch" section in the 
user-wide settings.json than hardcoded in our script. Remove the line to 
use VS Code's default, or the user's setting.

 > (Add his own configuration).

Avoid using gender-specific formulation when not needed. It's easier to 
do in English than in French.

 > Add useful links in contrib/vscode/README.md to help the user to
 > configure his VS Code and how to use the debugging feature.

Likewise.

 > Add a mention to the README in Documentation/MyFirstContribution.txt
 > and a part "To convince a newcomer that VS Code can help him".

Why use double-quotes here? You're not quoting anything, right?

> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1265,3 +1265,15 @@ against the appropriate GitGitGadget/Git branch.
> If you're using `git send-email`, you can use it the same way as before, but you
> should generate your diffs from `<topic>..<mybranch>` and base your work on
> `<topic>` instead of `master`.
> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== VS Code
> +
> +To see "how to use VS Code" read contrib/vscode/README.md.

Double-quotes look weird here too. And the document is not really about 
using VS Code, but more specifically on how to use VS Code on Git's 
codebase.

A set of scripts and instructions to use VS Code on Git's codebase is 
available in `contrib/vscode/README.md`.

?

> +If you want to try to understand "how git works internally", the debugging
> +feature of VS Code can help you. It will not give you all the keys to
> fully understand it, but
> +it can give you an idea of "how the information travels inside the code".
> +It can help you to isolate some parts of code, with this you are able
> +to ask more precise questions when you are stuck. (See getting-help sections).
> \ No newline at end of file

I'm reluctant to adding general programming tips in a Git-specific 
document. Perhaps shorten it to eg. just "Using the integrated debugger 
can be particularly helpful to understand how Git works internally"?

> --- a/contrib/vscode/README.md
> +++ b/contrib/vscode/README.md
> @@ -8,6 +8,11 @@ code editor which runs on your desktop and is available for
> [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
> it has [support for C/C++ via an
> extension](https://github.com/Microsoft/vscode-cpptools).
> +To understand "how works the debugging part" read:

"How the debugging part works" to get words in the proper order.

But the flow would be more natural continuing the previous sentence IMHO:

   it has [support for C/C++ via an 
extension](https://github.com/Microsoft/vscode-cpptools) with [debugging 
support](https://code.visualstudio.com/docs/editor/debugging).

> +To get help about "how to personalize your settings" read:
> +[How to set up your
> settings](https://code.visualstudio.com/docs/getstarted/settings)

Why not, but I don't think it's necessary here. People familiar with VS 
Code don't need such link, and people not familiar at all with is would 
better read a tutorial.

Cheers,

-- 
Matthieu Moy
https://matthieu-moy.fr/

[PATCH V1 0/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

> On 4/5/22 11:43, Matthieu Moy wrote:

> How did you generate this patch? It doesn't apply with 'git am', I 
> suspect you copy-pasted incorrectly into your mailer. Using 'git 
> send-email' helps sending properly formatted patches.

My bad, I copy and paste. 
I'm a bit ashamed to say it, but I didn't know about the command 'git am',
but never too late to know about it, so thanks.

> I usually explain the problem first, and then the solution.

Yes, if you don't mind, I take your explanation and put it inside the commit
because it sounds really good to me. So, if I had to add a special tag for 
this alert me.

> A set of scripts and instructions to use VS Code on Git's codebase is
> available in `contrib/vscode/README.md` ?.

Indeed, it's a bit confused the way I said it. So, I change the text 
to something more accurate.

> I'm reluctant to adding general programming tips in a Git-specific
> document. Perhaps shorten it to eg. just "Using the integrated debugger
> can be particularly helpful to understand how Git works internally"?

I know, it can be strange to talk about programming tips, but I also think that,
it can be a good idea if it could help a beginer. And I also think that, in 
MyFirstContribution it's the right place to talk about it, because it might be
the first reading of newcomers. But, maybe create another file to talk
about things like this with a mention of this file in MyFirstContribution 
can be good too.

> Why not, but I don't think it's necessary here. People familiar with VS
> Code don't need such link, and people not familiar at all with is would
> better read a tutorial.

You got a point, but like you said, why not.


Thanks for your help and for taking your time to review.



COGONI Guillaume (1):
  contrib/vscode/: debugging with VS Code and gdb

 Documentation/MyFirstContribution.txt | 11 +++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 16 insertions(+), 2 deletions(-)


Difference between V0 and V1
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 97f53f536d..7f48990cb8 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1271,9 +1271,8 @@ should generate your diffs from `<topic>..<mybranch>` and base your work on
 
 === VS Code
 
-To see "how to use VS Code" read contrib/vscode/README.md.
-If you want to try to understand "how git works internally", the debugging
-feature of VS Code can help you. It will not give you all the keys to fully understand it, but
-it can give you an idea of "how the informations travel inside the code".
-It can help you to isolate some parts of code, with this you are able
-to ask more precises question when you are stuck. (See getting-help sections).
+Using the integrate debugger can be particularly helpful to understand how Git works internally.
+It can be used to isolate some parts of code, with this you may be able to ask more precises
+question when you are stuck. (See getting-help sections).
+A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
+and explanation of how to use the script are available in contrib/vscode/README.md.

diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index a416a752c1..f383c95e1f 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -6,10 +6,9 @@ code editor which runs on your desktop and is available for
 [Windows](https://code.visualstudio.com/docs/setup/windows),
 [macOS](https://code.visualstudio.com/docs/setup/mac) and
 [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
-it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
+it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
+[debugging support](https://code.visualstudio.com/docs/editor/debugging)
 
-To understand "how works the debbuging part" read:
-[Help with the debbuging part](https://code.visualstudio.com/docs/editor/debugging)
 To get help about "how to personalize your settings" read:
 [How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)


-- 
2.25.1

[PATCH V1 1/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

The externalConsole=true setting is broken for many users (launching the
debugger with such setting results in VS Code waiting forever without
actually starting the debugger). Also, this setting is a matter of user
preference, and is arguably better set in a "launch" section in the
user-wide settings.json than hardcoded in our script. Remove the line to
use VS Code's default, or the user's setting.

Add useful links in contrib/vscode/README.md to help the user to
configure VS Code and how to use the debugging feature.

Add a mention to the README and the init.sh in Documentation/MyFirstContribution.txt
and a part to convince a newcomer that VS Code can help him.

Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Helped-by: Derrick Stolee <derrickstolee@github.com>
---
 Documentation/MyFirstContribution.txt | 11 +++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef5449..7f48990cb8 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1265,3 +1265,14 @@ against the appropriate GitGitGadget/Git branch.
 If you're using `git send-email`, you can use it the same way as before, but you
 should generate your diffs from `<topic>..<mybranch>` and base your work on
 `<topic>` instead of `master`.
+
+[[Bonus-useful-tools]]
+== Bonus - useful tools
+
+=== VS Code
+
+Using the integrate debugger can be particularly helpful to understand how Git works internally.
+It can be used to isolate some parts of code, with this you may be able to ask more precises
+question when you are stuck. (See getting-help sections).
+A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
+and explanation of how to use the script are available in contrib/vscode/README.md.
diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index 8202d62035..f383c95e1f 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
 [Windows](https://code.visualstudio.com/docs/setup/windows),
 [macOS](https://code.visualstudio.com/docs/setup/mac) and
 [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
-it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
+it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
+[debugging support](https://code.visualstudio.com/docs/editor/debugging)
+
+To get help about "how to personalize your settings" read:
+[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)
 
 To start developing Git with VS Code, simply run the Unix shell script called
 `init.sh` in this directory, which creates the configuration files in
diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b..f139fd8644 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
-- 
2.25.1

Re: [PATCH V1 1/1] contrib/vscode/: debugging with VS Code and gdb

[Ævar Arnfjörð Bjarmason]

On Wed, Apr 06 2022, COGONI Guillaume wrote:

> +Using the integrate debugger can be particularly helpful to understand how Git works internally.
> +It can be used to isolate some parts of code, with this you may be able to ask more precises
> +question when you are stuck. (See getting-help sections).
> +A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
> +and explanation of how to use the script are available in contrib/vscode/README.md.
> diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
> index 8202d62035..f383c95e1f 100644
> --- a/contrib/vscode/README.md
> +++ b/contrib/vscode/README.md
> @@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
>  [Windows](https://code.visualstudio.com/docs/setup/windows),
>  [macOS](https://code.visualstudio.com/docs/setup/mac) and
>  [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
> -it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
> +it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
> +[debugging support](https://code.visualstudio.com/docs/editor/debugging)
> +
> +To get help about "how to personalize your settings" read:
> +[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)
>  

The upthread "How did you generate this patch" question from Matthieu
still seems to apply. I.e.:

>  To start developing Git with VS Code, simply run the Unix shell script called
>  `init.sh` in this directory, which creates the configuration files in

This context is something that's not there in the file on "master".

I really don't mind having some guide for VSCode in our developer
documentation, but I think if we (as a free software project) are
recommending proprietary software we should put that in some context
where we explain if/why it's needed, and if free alternatives are also
suitable.

I haven't used the VSCode integration you're documenting, but from the
diff and the "gdb" mention I gather that this isn't using some "native"
debugger of MSVC/VS's, but just using the VSCode editor as a wrapper for
gdb?

If that's the case wouldn't it suffice to link to some generic getting
started guide for debuggers? And e.g. recommend the GDB manual, maybe
there's a better online reference (I read it locally), but e.g.:
https://www.sourceware.org/gdb/current/onlinedocs/gdb.html

Then if we're recommending GUI wrappers those are a dime a dozen,
e.g. Emacs's GUD mode:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Debuggers.html

Re: [PATCH V1 1/1] contrib/vscode/: debugging with VS Code and gdb

[Matthieu Moy]

On 4/6/22 00:45, COGONI Guillaume wrote:
> The externalConsole=true setting is broken for many users (launching the
> debugger with such setting results in VS Code waiting forever without
> actually starting the debugger). Also, this setting is a matter of user
> preference, and is arguably better set in a "launch" section in the
> user-wide settings.json than hardcoded in our script. Remove the line to
> use VS Code's default, or the user's setting.
> 
> Add useful links in contrib/vscode/README.md to help the user to
> configure VS Code and how to use the debugging feature.
> 
> Add a mention to the README and the init.sh in Documentation/MyFirstContribution.txt
> and a part to convince a newcomer that VS Code can help him.

You may avoid the gender-specific formulation here, women should be as 
interested as men in the document.

> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1265,3 +1265,14 @@ against the appropriate GitGitGadget/Git branch.
>   If you're using `git send-email`, you can use it the same way as before, but you
>   should generate your diffs from `<topic>..<mybranch>` and base your work on
>   `<topic>` instead of `master`.
> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== VS Code
> +
> +Using the integrate debugger can be particularly helpful to understand how Git works internally.
> +It can be used to isolate some parts of code, with this you may be able to ask more precises
> +question when you are stuck. (See getting-help sections).
> +A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
> +and explanation of how to use the script are available in contrib/vscode/README.md.

I'd start with the last sentence. People already familiar with VS Code 
may find the first line boring, and stop reading before reaching the 
important information.

With or without changes, this is

Acked-by: Matthieu Moy <git@matthieu-moy.fr>

--
Matthieu Moy
https://matthieu-moy.fr/

Re: [PATCH V1 1/1] contrib/vscode/: debugging with VS Code and gdb

[Matthieu Moy]

On 4/6/22 00:45, COGONI Guillaume wrote:
> The externalConsole=true setting is broken for many users (launching the
> debugger with such setting results in VS Code waiting forever without
> actually starting the debugger). Also, this setting is a matter of user
> preference, and is arguably better set in a "launch" section in the
> user-wide settings.json than hardcoded in our script. Remove the line to
> use VS Code's default, or the user's setting.
> 
> Add useful links in contrib/vscode/README.md to help the user to
> configure VS Code and how to use the debugging feature.
> 
> Add a mention to the README and the init.sh in Documentation/MyFirstContribution.txt
> and a part to convince a newcomer that VS Code can help him.

You may avoid the gender-specific formulation here, women should be as 
interested as men in the document.

> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1265,3 +1265,14 @@ against the appropriate GitGitGadget/Git branch.
>   If you're using `git send-email`, you can use it the same way as before, but you
>   should generate your diffs from `<topic>..<mybranch>` and base your work on
>   `<topic>` instead of `master`.
> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== VS Code
> +
> +Using the integrate debugger can be particularly helpful to understand how Git works internally.
> +It can be used to isolate some parts of code, with this you may be able to ask more precises
> +question when you are stuck. (See getting-help sections).
> +A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
> +and explanation of how to use the script are available in contrib/vscode/README.md.

I'd start with the last sentence. People already familiar with VS Code 
may find the first line boring, and stop reading before reaching the 
important information.

With or without changes, this is

Acked-by: Matthieu Moy <git@matthieu-moy.fr>

--
Matthieu Moy
https://matthieu-moy.fr/

[PATCH v2 0/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

> On 6/5/22 10:54 AM, Matthieu Moy wrote:

> but I think if we (as a free software project) are
> recommending proprietary software we should put that in some context
> where we explain if/why it's needed, and if free alternatives are also
> suitable.

> If that's the case wouldn't it suffice to link to some generic getting
> started guide for debuggers? 

You got a point, it's a bit paradoxical, but I don't know any good alternatives
and I don't want to advise someone with something that I don't be familiar with.
But, in the future, if someone wants to add alternatives it will be good.

> I haven't used the VSCode integration you're documenting, but from the
> diff and the "gdb" mention I gather that this isn't using some "native"
> debugger of MSVC/VS's, but just using the VSCode editor as a wrapper for
> gdb?

It can be use as a wrapper for the following debugger:
    Linux: GDB
    macOS: LLDB or GDB
    Windows: the Visual Studio Windows Debugger or GDB (using Cygwin or MinGW)
Source : https://code.visualstudio.com/docs/cpp/cpp-debug#_gdb-lldb-and-lldbmi-commands-gdblldb


Thanks for your reviewing.


> On 6/5/22 1:59 PM, Matthieu Moy wrote:

> I'd start with the last sentence. People already familiar with VS Code
> may find the first line boring, and stop reading before reaching the
> important information.

Yeah, sure, I don't think about the expert that must just want to know
about the script.

> Acked-by: Matthieu Moy <git@matthieu-moy.fr>

Thanks.


COGONI Guillaume (1):
  contrib/vscode/: debugging with VS Code and gdb

 Documentation/MyFirstContribution.txt | 11 +++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 16 insertions(+), 2 deletions(-)

Diff-intervalle between v1 and v2 :
1:  2a7d50ca5c ! 1:  367a478855 contrib/vscode/: debugging with VS Code and gdb
    @@ Commit message
    
    Add a mention to the README and the init.sh in Documentation/
    MyFirstContribution.txt and a part to convince a newcomer that VS Code
-   can help him.
+   can be helpful.
    
    Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
    Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>

    @@ Documentation/MyFirstContribution.txt: against the appropriate GitGitGadget/Git
+
+=== VS Code
+
++A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
++and explanation of how to use the script are available in contrib/vscode/README.md.
+Using the integrate debugger can be particularly helpful to understand how Git works internally.
+It can be used to isolate some parts of code, with this you may be able to ask more precises
+question when you are stuck. (See getting-help sections).
-+A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
-+and explanation of how to use the script are available in contrib/vscode/README.md.
\ No newline at end of file
    
    ## contrib/vscode/README.md ##
-- 
2.25.1

[PATCH v2 1/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

The externalConsole=true setting is broken for many users (launching the
debugger with such setting results in VS Code waiting forever without
actually starting the debugger). Also, this setting is a matter of user
preference, and is arguably better set in a "launch" section in the
user-wide settings.json than hardcoded in our script. Remove the line to
use VS Code's default, or the user's setting.

Add useful links in contrib/vscode/README.md to help the user to
configure VS Code and how to use the debugging feature.

Add a mention to the README and the init.sh in Documentation/
MyFirstContribution.txt and a part to convince a newcomer that VS Code
can be helpful.

Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Helped-by: Derrick Stolee <derrickstolee@github.com>
---
 Documentation/MyFirstContribution.txt | 11 +++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef5449..9cdb661271 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1265,3 +1265,14 @@ against the appropriate GitGitGadget/Git branch.
 If you're using `git send-email`, you can use it the same way as before, but you
 should generate your diffs from `<topic>..<mybranch>` and base your work on
 `<topic>` instead of `master`.
+
+[[Bonus-useful-tools]]
+== Bonus - useful tools
+
+=== VS Code
+
+A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
+and explanation of how to use the script are available in contrib/vscode/README.md.
+Using the integrate debugger can be particularly helpful to understand how Git works internally.
+It can be used to isolate some parts of code, with this you may be able to ask more precises
+question when you are stuck. (See getting-help sections).
\ No newline at end of file
diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index 8202d62035..f383c95e1f 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
 [Windows](https://code.visualstudio.com/docs/setup/windows),
 [macOS](https://code.visualstudio.com/docs/setup/mac) and
 [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
-it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
+it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
+[debugging support](https://code.visualstudio.com/docs/editor/debugging)
+
+To get help about "how to personalize your settings" read:
+[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)
 
 To start developing Git with VS Code, simply run the Unix shell script called
 `init.sh` in this directory, which creates the configuration files in
diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b..f139fd8644 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
-- 
2.25.1

Re: [PATCH v2 1/1] contrib/vscode/: debugging with VS Code and gdb

[Derrick Stolee]

On 4/6/2022 11:18 AM, COGONI Guillaume wrote:
> The externalConsole=true setting is broken for many users (launching the
> debugger with such setting results in VS Code waiting forever without
> actually starting the debugger). Also, this setting is a matter of user
> preference, and is arguably better set in a "launch" section in the
> user-wide settings.json than hardcoded in our script. Remove the line to
> use VS Code's default, or the user's setting.
> 
> Add useful links in contrib/vscode/README.md to help the user to
> configure VS Code and how to use the debugging feature.
> 
> Add a mention to the README and the init.sh in Documentation/
> MyFirstContribution.txt and a part to convince a newcomer that VS Code
> can be helpful.

Sorry for not getting to this in v1.
 
> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
> Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
> Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
> Helped-by: Derrick Stolee <derrickstolee@github.com>

Here, you probably want to flip the order here (Helped-by, then
Co-authored-by, then Signed-off-by). You probably also want the
sign-off of your co-author, too.

The sign-off should be the last thing in the message, because
the previous lines are covered by that sign-off.

> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== VS Code

Here, maybe use the full name, then the short version.

 === Visual Studio Code (VS Code)

> +A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
> +and explanation of how to use the script are available in contrib/vscode/README.md.

This passive voice could be made active such as:

  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.

Make a new paragraph before talking about debuggers.

> +Using the integrate debugger can be particularly helpful to understand how Git works internally.
> +It can be used to isolate some parts of code, with this you may be able to ask more precises
> +question when you are stuck. (See getting-help sections).

I would focus less on "benefits of debugging" and focus instead on
"benefits of debugging using your GUI editor". Something like this
might be a good start:

  In particular, this script enables using the VS Code visual debugger,
  including setting breakpoints in the editor.

> \ No newline at end of file

Fix this missing newline.

> diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
> index 8202d62035..f383c95e1f 100644
> --- a/contrib/vscode/README.md
> +++ b/contrib/vscode/README.md
> @@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
>  [Windows](https://code.visualstudio.com/docs/setup/windows),
>  [macOS](https://code.visualstudio.com/docs/setup/mac) and
>  [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
> -it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
> +it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
> +[debugging support](https://code.visualstudio.com/docs/editor/debugging)
> +
> +To get help about "how to personalize your settings" read:
> +[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)

These changes are pretty standard, and I have no concerns here.

>              "stopAtEntry": false,
>              "cwd": "\${workspaceFolder}",
>              "environment": [],
> -            "externalConsole": true,

And this is the necessary fix.

Thanks for working on this!

Thanks,
-Stolee

Re: [PATCH v2 1/1] contrib/vscode/: debugging with VS Code and gdb

[Junio C Hamano]

Derrick Stolee <derrickstolee@github.com> writes:

>  
>> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
>> Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
>> Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
>> Helped-by: Derrick Stolee <derrickstolee@github.com>
>
> Here, you probably want to flip the order here (Helped-by, then
> Co-authored-by, then Signed-off-by). You probably also want the
> sign-off of your co-author, too.
>
> The sign-off should be the last thing in the message, because
> the previous lines are covered by that sign-off.

Yup.  It would record the order of events that lead to this exact
patch, which is what we want to capture.  With help by these people,
together with the co-author(s), the patch was written and author(s)
signed-off before it was sent out to the list.

> ...
> And this is the necessary fix.
>
> Thanks for working on this!

Indeed.  And thanks for a helpful review.

[PATCH v3 0/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

On 4/6/2022 18:03 PM, Derrick Stolee wrote:

> Sorry for not getting to this in v1.

No problem, I take this opportunity to get a better view of the review 
process.

> Thanks for working on this!

Thanks for your help and reviewing.


COGONI Guillaume (1):
  contrib/vscode/: debugging with VS Code and gdb

 Documentation/MyFirstContribution.txt | 20 ++++++++++++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 25 insertions(+), 2 deletions(-)

Diff-intervalle between v2 and v3 :
1:  367a478855 ! 1:  0600ab64f8 contrib/vscode/: debugging with VS Code and gdb
@@ Commit message
     MyFirstContribution.txt and a part to convince a newcomer that VS Code
     can be helpful.
     
-    Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
-    Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
     Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
     Helped-by: Derrick Stolee <derrickstolee@github.com>
+    Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
+    Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
     
     ## Documentation/MyFirstContribution.txt ##
     @@ Documentation/MyFirstContribution.txt: against the appropriate GitGitGadget/Git branch.
@@ Documentation/MyFirstContribution.txt: against the appropriate GitGitGadget/Git
+[[Bonus-useful-tools]]
+== Bonus - useful tools
+
-+=== VS Code
+=== 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.
+
-A script that creates the configuration files is available in contrib/vscode/init.sh. Useful links
-and explanation of how to use the script are available in contrib/vscode/README.md.
-Using the integrate debugger can be particularly helpful to understand how Git works internally.
-It can be used to isolate some parts of code, with this you may be able to ask more precises
-question when you are stuck. (See getting-help sections).
- \ No newline at end of file
+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. (See getting-help sections).
     
     ## contrib/vscode/README.md ##
     @@ contrib/vscode/README.md: code editor which runs on your desktop and is available for
-- 
2.25.1

[PATCH v3 1/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

The externalConsole=true setting is broken for many users (launching the
debugger with such setting results in VS Code waiting forever without
actually starting the debugger). Also, this setting is a matter of user
preference, and is arguably better set in a "launch" section in the
user-wide settings.json than hardcoded in our script. Remove the line to
use VS Code's default, or the user's setting.

Add useful links in contrib/vscode/README.md to help the user to
configure VS Code and how to use the debugging feature.

Add a mention to the README and the init.sh in Documentation/
MyFirstContribution.txt and a part to convince a newcomer that VS Code
can be helpful.

Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Helped-by: Derrick Stolee <derrickstolee@github.com>
Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
---
 Documentation/MyFirstContribution.txt | 20 ++++++++++++++++++++
 contrib/vscode/README.md              |  6 +++++-
 contrib/vscode/init.sh                |  1 -
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef5449..fc53456527 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1265,3 +1265,23 @@ against the appropriate GitGitGadget/Git branch.
 If you're using `git send-email`, you can use it the same way as before, but you
 should generate your diffs from `<topic>..<mybranch>` and base your work on
 `<topic>` instead of `master`.
+
+[[Bonus-useful-tools]]
+== Bonus - useful tools
+
+=== 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. (See getting-help sections).
diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index 8202d62035..f383c95e1f 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
 [Windows](https://code.visualstudio.com/docs/setup/windows),
 [macOS](https://code.visualstudio.com/docs/setup/mac) and
 [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
-it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
+it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
+[debugging support](https://code.visualstudio.com/docs/editor/debugging)
+
+To get help about "how to personalize your settings" read:
+[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)
 
 To start developing Git with VS Code, simply run the Unix shell script called
 `init.sh` in this directory, which creates the configuration files in
diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b..f139fd8644 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
-- 
2.25.1

Re: [PATCH v3 1/1] contrib/vscode/: debugging with VS Code and gdb

[Ævar Arnfjörð Bjarmason]

[Partially in reply to Matthieu Moy's
https://lore.kernel.org/git/6a5152c1-7bb4-220c-cdce-33e93ea9c7c6@univ-lyon1.fr/,
but it seems more useful to continue here in the v3 thread]

On Thu, Apr 07 2022, COGONI Guillaume wrote:

> Add a mention to the README and the init.sh in Documentation/
> MyFirstContribution.txt and a part to convince a newcomer that VS Code
> can be helpful.

Aside from this specific addition of a section about VSCode it says at
the top of of Documentation/MyFirstContribution.txt:
	
	This tutorial aims to summarize the following documents, but the reader may find
	useful additional context:
	
	- `Documentation/SubmittingPatches`
	- `Documentation/howto/new-command.txt`

Should we have anything in MyFirstContribution.txt that isn't already
covered there per that statement at the top?

[Combining replies at this point]

On Thu, Apr 07 2022, Matthieu Moy wrote:

> On 4/6/22 10:47, Ævar Arnfjörð Bjarmason wrote:
>> On Wed, Apr 06 2022, COGONI Guillaume wrote:
>> I really don't mind having some guide for VSCode in our developer
>> documentation, but I think if we (as a free software project) are
>> recommending proprietary software we should put that in some context
>> where we explain if/why it's needed, and if free alternatives are also
>> suitable.
>
> Note that VS Code is mostly open source (the pre-compiled binaries are
> proprietary, but the source code is MIT licenced, 
> https://github.com/Microsoft/vscode). Not to be confused with Visual
> Studio, which is fully proprietary, but is a totally different tool 
> (AFAIK, they only share the name).

This patch specifically proposed to link to the propriterary version.

Is there a reason we wouldn't at least recommend the fully-free version
at https://github.com/VSCodium/vscodium, or at least mention it as
prominently?

>> I haven't used the VSCode integration you're documenting, but from the
>> diff and the "gdb" mention I gather that this isn't using some "native"
>> debugger of MSVC/VS's, but just using the VSCode editor as a wrapper for
>> gdb?
>
> Yes (gdb or lldb under the hood). As usual, it adds a GUI layer, but
> also a configuration layer where you specify how to launch the
> debugger in a launch.json file, and this is where the little script in
> contrib/ is handy to generate a launch.json adapted for Git.
>
>> If that's the case wouldn't it suffice to link to some generic getting
>> started guide for debuggers? And e.g. recommend the GDB manual, maybe
>> there's a better online reference (I read it locally), but e.g.:
>> https://www.sourceware.org/gdb/current/onlinedocs/gdb.html
>
> To me the point of the doc within Git's repo is to document
> git-specific aspects, and I agree that pointing to a generic doc is
> better than re-writing one. If I had written the patch I'd have made
> the general paragraph on debugger benefits a bit shorter, but it's
> already rather short so I'm OK with the patch in its current state.
>
>> Then if we're recommending GUI wrappers those are a dime a dozen,
>> e.g. Emacs's GUD mode:
>> https://www.gnu.org/software/emacs/manual/html_node/emacs/Debuggers.html
>
> To me this is out of the scope of the patch (the real point to me was
> to increase the discoverability of contrib/vscode), but sure,
> documenting other GUI wrappers would be nice.
> [...]
> +
> +[[Bonus-useful-tools]]
> +== Bonus - useful tools
> +
> +=== 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. (See getting-help sections).
> diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
> index 8202d62035..f383c95e1f 100644
> --- a/contrib/vscode/README.md
> +++ b/contrib/vscode/README.md
> @@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
>  [Windows](https://code.visualstudio.com/docs/setup/windows),
>  [macOS](https://code.visualstudio.com/docs/setup/mac) and
>  [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
> -it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
> +it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
> +[debugging support](https://code.visualstudio.com/docs/editor/debugging)
> +
> +To get help about "how to personalize your settings" read:
> +[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)

Two things:

First I think (disclaimer: being on the Git PLC this is just my opinion)
that as a prominent free software project, and being under the Software
Freedom Conservancy umbrella whose mission is
(https://sfconservancy.org/):

    [...] fostering free and open source software (FOSS) projects,
    driving initiatives that actively make technology more inclusive,
    and advancing policy strategies that defend FOSS (such as copyleft).

So, maybe I'm just an old free software radical, but I believe in
interpreting that broadly. I.e. if we're recommending third-party
software we should prefer free alternatives, which doesn't mean that we
can't mention proprietary software, just that we shouldn't be
encouraging it when a free alternative will do.

But secondly, and everything here would apply if VSCode were replaced by
GNU Emacs and its GUD mode, so it's not about free software on VSCode at
all: This whole addition just seems like it's recommending a needlessly
complex way to get to having a C debugger installed.

Leaving aside completely *where* we should put such a thing I'd expect
something much more like:
	
	BEGIN QUOTE
	
	== 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 ===
	
	Some users find using such a debugger to be rather "bare bones" on the
	command-line, but there's numerous GUIs or "front-ends" for them
	available. You may even find that your editort (e.g. GNU emacs) ships
	with such a frontend already. You may find a listing of some at (some of
	these work with lldb as well as gdb):
	
	    http://sourceware.org/gdb/wiki/GDB%20Front%20Ends
	
	We also have helper code in-tree to launch debuggers from some
	editors. If you use on of these editors you may find that handy:
	
		VSCode: contrib/vscode/README.md
	
	=== Debugging test failures ===
	
	If you'd like to start an interactive debugger at the ponit where a test
	fails you may find the "debug" wrapper in t/test-lib-functions.sh useful
	for that.
	
	END QUOTE

I.e. it really shouldn't be the goal of a section on debuggers to
"convince a newcomer that VS Code can be helpful", or that Emacs is
helpful or whatever. Let's instead discuss the general topic at hand.

The proposed addition buries the lede in that regard. I.e. it's not made
clear to the reader that we're just suggesting yet another interface for
gdb, so a beginning contributor might go through it, only to find that
all they needed was gdb, and they had that installed already.

Re: [PATCH v3 1/1] contrib/vscode/: debugging with VS Code and gdb

[Derrick Stolee]

On 4/7/2022 7:17 AM, Ævar Arnfjörð Bjarmason wrote:
>> On 4/6/22 10:47, Ævar Arnfjörð Bjarmason wrote:
>>> On Wed, Apr 06 2022, COGONI Guillaume wrote:
>>> I really don't mind having some guide for VSCode in our developer
>>> documentation, but I think if we (as a free software project) are
>>> recommending proprietary software we should put that in some context
>>> where we explain if/why it's needed, and if free alternatives are also
>>> suitable.
>>
>> Note that VS Code is mostly open source (the pre-compiled binaries are
>> proprietary, but the source code is MIT licenced, 
>> https://github.com/Microsoft/vscode). Not to be confused with Visual
>> Studio, which is fully proprietary, but is a totally different tool 
>> (AFAIK, they only share the name).
> 
> This patch specifically proposed to link to the propriterary version.
> 
> Is there a reason we wouldn't at least recommend the fully-free version
> at https://github.com/VSCodium/vscodium, or at least mention it as
> prominently?

I think it is find to add such a reference, but I doubt it will have
much value to the reader. If the strangeness around how VS Code is
compiled bothers the reader, then they probably already avoid it.

I think this is an excellent thing to consider as a follow-up by an
expert on the topic, such as yourself, and not prevent this patch from
moving forward from the current authors.

> Two things:
> 
> First I think (disclaimer: being on the Git PLC this is just my opinion)
> that as a prominent free software project, and being under the Software
> Freedom Conservancy umbrella whose mission is
> (https://sfconservancy.org/):
> 
>     [...] fostering free and open source software (FOSS) projects,
>     driving initiatives that actively make technology more inclusive,
>     and advancing policy strategies that defend FOSS (such as copyleft).
> 
> So, maybe I'm just an old free software radical, but I believe in
> interpreting that broadly. I.e. if we're recommending third-party
> software we should prefer free alternatives, which doesn't mean that we
> can't mention proprietary software, just that we shouldn't be
> encouraging it when a free alternative will do.

Sometimes, we need to meet people where they are. If they choose to
use a proprietary editor, we can help them use that to work on our
project.

> But secondly, and everything here would apply if VSCode were replaced by
> GNU Emacs and its GUD mode, so it's not about free software on VSCode at
> all: This whole addition just seems like it's recommending a needlessly
> complex way to get to having a C debugger installed.

I completely agree with you that this should be the _start_ of the
process of documenting how to debug with a bunch of editors. There are
benefits of connecting your editor to the debugger instead of relying
on gdb or whatever directly.

I also find it hard to interpret the current section as "Do you want to
debug Git?  You should use VS Code!" I _can_ see that the section on
"useful tools" only contains one entry (so far) and that can be
read as a recommendation. This should motivate those who use other tools
to chime in with how they use their tools and what steps are required to
get efficient integrations when working on Git.

> Leaving aside completely *where* we should put such a thing I'd expect
> something much more like:
> 	
> 	BEGIN QUOTE
> 	
> 	== Using debuggers ==
...
> 	=== GUIs ===
...

I was trying to make a similar recommendation in my review. The point is
not "You should use a debugger, here is VS Code", but rather "If you want
to use a debugger with your editor, here are ways to configure your
editor of choice to debug Git." It is perfectly fine by me if these
authors want to start with the editor they know and use, as long as the
structure is such that it can be extended by other contributors to
include these other editor.

> 	=== Debugging test failures ===
> 	
> 	If you'd like to start an interactive debugger at the ponit where a test
> 	fails you may find the "debug" wrapper in t/test-lib-functions.sh useful
> 	for that.

This is a helpful idea to include in this section, but it is far too
terse to be helpful to someone who doesn't know exactly what you mean
by a '"debug" wrapper'. An example would go far here. This also
requires working with the command-line debugger (gdb, lldb, etc.), so
should be carefully differentiated from the GUI section. One way to
establish that difference would be to move it above the GUI section.

> I.e. it really shouldn't be the goal of a section on debuggers to
> "convince a newcomer that VS Code can be helpful", or that Emacs is
> helpful or whatever. Let's instead discuss the general topic at hand.
> 
> The proposed addition buries the lede in that regard. I.e. it's not made
> clear to the reader that we're just suggesting yet another interface for
> gdb, so a beginning contributor might go through it, only to find that
> all they needed was gdb, and they had that installed already.

I think that having a section on using debuggers in general, followed
by specific ways to interact with a variety of editors, would be helpful.

But I also think that this contribution does not need to be burdened by
that increase in scope. The heading "Bonus - useful tools" is a good
start that can be extended in several ways by future contributions. One
way is to reframe it as "how to debug Git" while another might be to
add other useful tools like clang-format or valgrind. I believe the best
way to go here is to be happy with the contribution with its current
scope and leave these later discussions for contributors with the right
expertise and time to write more documentation.

----

Perhaps this entire discussion would be different if the change was
added somewhere other than MyFirstContribution.txt. Is there a better
file to place this change?

MyFirstContribution.txt provides a good start to the basics of
making change, with a specific example giving chronological steps
for submitting a change. It seems like adding a section at the end
of "bonus tools" does not fit that narrative.

Taking a look myself, the only other places that _might_ make sense
include CodingGuidelines (has some integrations with Emacs included)
or SubmittingPatches (talks a lot about different email clients and
tools that help).

I think that we might want a new file where Git developers can
share best practices and custom workflows. Such a document could
help contributors optimize their process to their own tastes based
on the experience of others. I can see a long list of integrations
with editors fitting in there, along with tips like "create a RAM
disk for running tests".

My proposed name for such a file is "WorkingOnGit" but it's not
fantastic. Suggestions welcome.

---

Cogoni: In conclusion, I think that if you remove the change to
MyFirstContribution.txt, then your patch can be merged pretty
quickly (probably, that's not my decision). I expect this discussion
about a potential "WorkingOnGit" file to continue, but if it comes
to fruition, your section on VS Code would be welcome.

Thanks,
-Stolee

Re: [PATCH v3 1/1] contrib/vscode/: debugging with VS Code and gdb

[Junio C Hamano]

Derrick Stolee <derrickstolee@github.com> writes:

> Sometimes, we need to meet people where they are. If they choose to
> use a proprietary editor, we can help them use that to work on our
> project.

Yes, that's a good point to make.  I found that the thrust of the
suggestion made in the last part of Ævar's message was "if you are
user of VSCode, what we have in contrib/ may help your use of
debuggers in it", which was in line with the above.

>> Leaving aside completely *where* we should put such a thing I'd expect
>> something much more like:
>> 	
>> 	BEGIN QUOTE
>> 	
>> 	== Using debuggers ==
> ...
>> 	=== GUIs ===
> ...
>
> I was trying to make a similar recommendation in my review. The point is
> not "You should use a debugger, here is VS Code", but rather ...

Yup, I guess that makes three of us?

> I think that we might want a new file where Git developers can
> share best practices and custom workflows. Such a document could
> help contributors optimize their process to their own tastes based
> on the experience of others. I can see a long list of integrations
> with editors fitting in there, along with tips like "create a RAM
> disk for running tests".
>
> My proposed name for such a file is "WorkingOnGit" but it's not
> fantastic. Suggestions welcome.

Sounds like a good thing to have, but would there truly be hints and
tips so specific to this project, I have to wonder.  I do not think
we are in the business of making "how to hack on and debug a project
code that is mostly written in C and whose history is managed in
Git" tutorial for each IDE, so I am not sure how well it would fly
(not opposed to, but skeptical).

> Cogoni: In conclusion, I think that if you remove the change to
> MyFirstContribution.txt, then your patch can be merged pretty
> quickly (probably, that's not my decision). I expect this discussion
> about a potential "WorkingOnGit" file to continue, but if it comes
> to fruition, your section on VS Code would be welcome.

Yeah, the change to that document did feel like it was working at a
different level from other changes.

Thanks.

[PATCH v4 0/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=[UTF-8], Size: 3948 bytes --]

Derrick Stolee <derrickstolee@github.com> writes:

> Cogoni: In conclusion, I think that if you remove the change to
> MyFirstContribution.txt, then your patch can be merged pretty
> quickly (probably, that's not my decision). 
> I expect this discussion about a potential "WorkingOnGit" file to continue, 
> but if it come to fruition, your section on VS Code would be welcome.

Yes, I got the same conclusion, from the discussion between you and
Ævar Arnfjörð Bjarmason. So, I remove the change to MyFirstContribution.txt.
It sounds like the best plan for now.

But, I agreed on some point with Ævar Arnfjörð Bjarmason, we have to try 
to recommending also free alternatives.

And, yes, a new file is the best option. So, I keep my change somewhere, and 
I will come again with a new patch but not in its thread because it seems to 
be out of the scope now.


> Sounds like a good thing to have, but would there truly be hints and
> tips so specific to this project, I have to wonder. I do not think
> we are in the business of making "how to hack on and debug a project
> code that is mostly written in C and whose history is managed in
> Git" tutorial for each IDE, so I am not sure how well it would fly
> (not opposed to, but skeptical).

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.

Thanks everyone for your reviews, your ideas and help.


COGONI Guillaume (1):
  contrib/vscode/: debugging with VS Code and gdb

 contrib/vscode/README.md | 6 +++++-
 contrib/vscode/init.sh   | 1 -
 2 files changed, 5 insertions(+), 2 deletions(-)

Diff-intervalle vs v3 :
1:  0600ab64f8 ! 1:  59de991a2d contrib/vscode/: debugging with VS Code and gdb
    @@ Commit message
         Add useful links in contrib/vscode/README.md to help the user to
         configure VS Code and how to use the debugging feature.
     
    -    Add a mention to the README and the init.sh in Documentation/
    -    MyFirstContribution.txt and a part to convince a newcomer that VS Code
    -    can be helpful.
    -
         Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
         Helped-by: Derrick Stolee <derrickstolee@github.com>
         Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
         Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
     
    - ## Documentation/MyFirstContribution.txt ##
    -@@ Documentation/MyFirstContribution.txt: against the appropriate GitGitGadget/Git branch.
    - If you're using `git send-email`, you can use it the same way as before, but you
    - should generate your diffs from `<topic>..<mybranch>` and base your work on
    - `<topic>` instead of `master`.
    -+
    -+[[Bonus-useful-tools]]
    -+== Bonus - useful tools
    -+
    -+=== 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. (See getting-help sections).
    -
      ## contrib/vscode/README.md ##
     @@ contrib/vscode/README.md: code editor which runs on your desktop and is available for
      [Windows](https://code.visualstudio.com/docs/setup/windows),
-- 
2.25.1

[PATCH v4 1/1] contrib/vscode/: debugging with VS Code and gdb

[COGONI Guillaume]

The externalConsole=true setting is broken for many users (launching the
debugger with such setting results in VS Code waiting forever without
actually starting the debugger). Also, this setting is a matter of user
preference, and is arguably better set in a "launch" section in the
user-wide settings.json than hardcoded in our script. Remove the line to
use VS Code's default, or the user's setting.

Add useful links in contrib/vscode/README.md to help the user to
configure VS Code and how to use the debugging feature.

Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr>
Helped-by: Derrick Stolee <derrickstolee@github.com>
Co-authored-by: BRESSAT Jonathan <git.jonathan.bressat@gmail.com>
Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com>
---
 contrib/vscode/README.md | 6 +++++-
 contrib/vscode/init.sh   | 1 -
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md
index 8202d62035..f383c95e1f 100644
--- a/contrib/vscode/README.md
+++ b/contrib/vscode/README.md
@@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for
 [Windows](https://code.visualstudio.com/docs/setup/windows),
 [macOS](https://code.visualstudio.com/docs/setup/mac) and
 [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages,
-it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools).
+it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with
+[debugging support](https://code.visualstudio.com/docs/editor/debugging)
+
+To get help about "how to personalize your settings" read:
+[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings)
 
 To start developing Git with VS Code, simply run the Unix shell script called
 `init.sh` in this directory, which creates the configuration files in
diff --git a/contrib/vscode/init.sh b/contrib/vscode/init.sh
index 27de94994b..f139fd8644 100755
--- a/contrib/vscode/init.sh
+++ b/contrib/vscode/init.sh
@@ -271,7 +271,6 @@ cat >.vscode/launch.json.new <<EOF ||
             "stopAtEntry": false,
             "cwd": "\${workspaceFolder}",
             "environment": [],
-            "externalConsole": true,
             "MIMode": "gdb",
             "miDebuggerPath": "$GDBPATH",
             "setupCommands": [
-- 
2.25.1

Re: [PATCH V1 1/1] contrib/vscode/: debugging with VS Code and gdb

[Matthieu Moy]

On 4/6/22 10:47, Ævar Arnfjörð Bjarmason wrote:
> 
> On Wed, Apr 06 2022, COGONI Guillaume wrote:
> 
> I really don't mind having some guide for VSCode in our developer
> documentation, but I think if we (as a free software project) are
> recommending proprietary software we should put that in some context
> where we explain if/why it's needed, and if free alternatives are also
> suitable.

Note that VS Code is mostly open source (the pre-compiled binaries are 
proprietary, but the source code is MIT licenced, 
https://github.com/Microsoft/vscode). Not to be confused with Visual 
Studio, which is fully proprietary, but is a totally different tool 
(AFAIK, they only share the name).

> I haven't used the VSCode integration you're documenting, but from the
> diff and the "gdb" mention I gather that this isn't using some "native"
> debugger of MSVC/VS's, but just using the VSCode editor as a wrapper for
> gdb?

Yes (gdb or lldb under the hood). As usual, it adds a GUI layer, but 
also a configuration layer where you specify how to launch the debugger 
in a launch.json file, and this is where the little script in contrib/ 
is handy to generate a launch.json adapted for Git.

> If that's the case wouldn't it suffice to link to some generic getting
> started guide for debuggers? And e.g. recommend the GDB manual, maybe
> there's a better online reference (I read it locally), but e.g.:
> https://www.sourceware.org/gdb/current/onlinedocs/gdb.html

To me the point of the doc within Git's repo is to document git-specific 
aspects, and I agree that pointing to a generic doc is better than 
re-writing one. If I had written the patch I'd have made the general 
paragraph on debugger benefits a bit shorter, but it's already rather 
short so I'm OK with the patch in its current state.

> Then if we're recommending GUI wrappers those are a dime a dozen,
> e.g. Emacs's GUD mode:
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Debuggers.html

To me this is out of the scope of the patch (the real point to me was to 
increase the discoverability of contrib/vscode), but sure, documenting 
other GUI wrappers would be nice.

-- 
Matthieu Moy
https://matthieu-moy.fr/