doc: hint about GIT_DEBUGGER
PATCH 1/1 doc: hint about GIT_DEBUGGER
We check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).
It looks like you can use GIT_DEBUGGER to pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). Hopefully document that intent within CodingGuidelines.
---
Maybe this isn't the right place for this patch. But right now git grep reveals that GIT_DEBUGGER is completely undocumented.
Alternatively, it might make sense to only add a short blurb about using GIT_DEBUGGER flag to CodingGuidelines and then documenting how to use it inside of wrap-for-bin.sh.
Documentation/CodingGuidelines | 5 +++++ 1 file changed, 5 insertions(+)
Documentation/CodingGuidelines +5 -0
@@ -412,6 +412,11 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=debugger-binary some-args ./bin-wrappers/git foo` to + use your own debugger and arguments. (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply.
Signature · 1 line
2.21.0.1020.gf2820cf01a-goog
Hi Emily,
Quoted 10 lines · Emily Shaffer
We check for a handy environment variable
GIT_DEBUGGERwhen running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).It looks like you can use
GIT_DEBUGGERto pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). Hopefully document that intent within CodingGuidelines.
Thanks for working on this.
Quoted 4 lines
Signed-off-by Emily Shaffer <[email protected]>---
Maybe this isn't the right place for this patch. But right now git grep reveals thatGIT_DEBUGGERis completely undocumented.
Does 'git log --grep=GIT_DEBUGGER' count? ;-)
Quoted 12 lines
Alternatively, it might make sense to only add a short blurb about using
GIT_DEBUGGERflag to CodingGuidelines and then documenting how to use it inside ofwrap-for-bin.sh.Documentation/CodingGuidelines | 5 +++++ 1 file changed, 5 insertions(+)Documentation/CodingGuidelines +0
-0
Documentation/CodingGuidelines For C programs: · line 417
Quoted 6 lines
Documentation/CodingGuidelines +3
-0@@ -412,6 +412,11 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=debugger-binary some-args ./bin-wrappers/git foo` to
Missing some quotes around debugger-binary and some-args:
+ run GIT_DEBUGGER="debugger-binary some-args" ./bin-wrappers/git foo to
Also, one thing I always wonder about with command documentation like this is whether people will understand that "debugger-binary", "some-args", and "foo" are just placeholders rather than literal text -- and that everything else is literal text and not meant to be placeholders. Does it make since to include a couple examples, or perhaps modify the text somehow to avoid confusion between placeholders and literals, or maybe just tell me I overthinking this? (I've been bit by similar problems in other contexts, so I'm just flagging it for you to consider).
Elijah
[snip]
Quoted 7 lines
Documentation/CodingGuidelines For C programs: · line 417
Quoted 3 lines
+ - You can launch gdb around your program using the shorthand
GIT_DEBUGGER.Documentation/CodingGuidelines +2
-0+ Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=debugger-binary some-args ./bin-wrappers/git foo` toMissing some quotes around debugger-binary and some-args:
+ runGIT_DEBUGGER="debugger-binary some-args" ./bin-wrappers/git footo
Quoted 9 lines
Also, one thing I always wonder about with command documentation like this is whether people will understand that "debugger-binary", "some-args", and "foo" are just placeholders rather than literal text -- and that everything else is literal text and not meant to be placeholders. Does it make since to include a couple examples, or perhaps modify the text somehow to avoid confusion between placeholders and literals, or maybe just tell me I overthinking this? (I've been bit by similar problems in other contexts, so I'm just flagging it for you to consider).
It's a good point. I like to use placeholders that don't sound like a real command (and failed a little here), for example, GIT_DEBUGGER=my-cool-debugger some-various-args. It can be a challenge to choose a placeholder that sounds fake but also doesn't sound too informal (the above feels informal to me). I think the best way is to show an example, that's a good idea. I'll come up with one and send another round this week.
Thanks a bunch for having a look.
- Emily
Quoted 2 lines
Elijah
PATCH v2 1/1 doc: hint about GIT_DEBUGGER
In reply to Emily ShafferWe check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).
It looks like you can use GIT_DEBUGGER to pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). Hopefully document that intent within CodingGuidelines.
--- Documentation/CodingGuidelines | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/CodingGuidelines +6 -0
@@ -412,6 +412,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply.
Signature · 1 line
2.21.0.1020.gf2820cf01a-goog
Quoted 6 lines · Emily Shaffer
We check for a handy environment variable
GIT_DEBUGGERwhen running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).
Two very minor nits:
Quoted 1 line
It looks like you can use
GIT_DEBUGGERto pick gdb by default, or you
I think it'd sound better without 'It looks like'; perhaps drop that part?
Quoted 3 lines
can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). Hopefully document that intent within CodingGuidelines.
Maybe just leave out 'Hopefully'?
Quoted 11 lines
Signed-off-by Emily Shaffer <[email protected]>--- Documentation/CodingGuidelines | 6 ++++++ 1 file changed, 6 insertions(+)Documentation/CodingGuidelines +0
-0
Documentation/CodingGuidelines For C programs: · line 420
Quoted 9 lines
Documentation/CodingGuidelines +6
-0@@ -412,6 +412,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) +
Other than the minor nits above:
Quoted 42 lines · Elijah Newren
Quoted 6 lines · Emily Shaffer
We check for a handy environment variable
GIT_DEBUGGERwhen running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).Two very minor nits:
Quoted 1 line
It looks like you can use
GIT_DEBUGGERto pick gdb by default, or youI think it'd sound better without 'It looks like'; perhaps drop that part?
Quoted 3 lines
can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). Hopefully document that intent within CodingGuidelines.
Maybe just leave out 'Hopefully'?
Quoted 11 lines
Signed-off-by Emily Shaffer <[email protected]>--- Documentation/CodingGuidelines | 6 ++++++ 1 file changed, 6 insertions(+)Documentation/CodingGuidelines +0
-0Documentation/CodingGuidelines For C programs: · line 420
Quoted 9 lines
Documentation/CodingGuidelines +6
-0@@ -412,6 +412,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) +Other than the minor nits above:
Quoted 1 line
Acked-by Elijah Newren <[email protected]>
Made both the changes you recommended; I'll hang onto it locally until this afternoon in case anybody else has something to say. Thanks for looking, Elijah.
- Emily
PATCH v3 1/1 doc: hint about GIT_DEBUGGER in CodingGuidelines
In reply to Emily ShafferWe check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).
You can use GIT_DEBUGGER to pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). This commit documents that intent within CodingGuidelines.
---
Since v2, only the commit message has changed. Removed some weak language to make the commit message read more easily.
Documentation/CodingGuidelines | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/CodingGuidelines +6 -0
@@ -412,6 +412,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply.
Signature · 1 line
2.21.0.1020.gf2820cf01a-goog
Re: [PATCH v3] doc: hint about GIT_DEBUGGER in CodingGuidelines
Quoted 9 lines · Emily Shaffer
We check for a handy environment variable
GIT_DEBUGGERwhen running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).You can use
GIT_DEBUGGERto pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). This commit documents that intent within CodingGuidelines.
This last sentence is repeating what is already stated in the first paragraph, thus doesn't seem to add value. In fact, the remainder of the second paragraph seems to be repeating what is in the patch proper, thus could likely be dropped.
Documentation/CodingGuidelines For C programs: · line 414
Quoted 7 lines
Signed-off-by Emily Shaffer <[email protected]>---
Documentation/CodingGuidelines +3
-0@@ -412,6 +412,12 @@ For C programs: + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` to
Don't you need to bind my-debugger-binary and my-args together with shell quotes? Also, placeholders like these are often ensconced in angle brackets, so perhaps:
... `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git ...
Quoted 2 lines
Documentation/CodingGuidelines +2
-0+ use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.)
Re: [PATCH v3] doc: hint about GIT_DEBUGGER in CodingGuidelines
Quoted 11 lines · Eric Sunshine
Quoted 9 lines · Emily Shaffer
We check for a handy environment variable
GIT_DEBUGGERwhen running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).You can use
GIT_DEBUGGERto pick gdb by default, or you can hand it your own debugger if you like to use something else (or if you want custom flags for gdb). This commit documents that intent within CodingGuidelines.
Quoted 4 lines
This last sentence is repeating what is already stated in the first paragraph, thus doesn't seem to add value. In fact, the remainder of the second paragraph seems to be repeating what is in the patch proper, thus could likely be dropped.
Yes, you're right. Dropped.
Quoted 13 lines
Documentation/CodingGuidelines For C programs: · line 414
Quoted 8 lines
Signed-off-by Emily Shaffer <[email protected]>---
Documentation/CodingGuidelines +3
-0@@ -412,6 +412,12 @@ For C programs: + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER=my-debugger-binary my-args ./bin-wrappers/git foo` toDon't you need to bind my-debugger-binary and my-args together with shell quotes? Also, placeholders like these are often ensconced in angle brackets, so perhaps:
Quoted 1 line
... `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git ...
Fixed. I did get the dq in the example but missed it with the placeholders. :) Thanks, good catch.
Quoted 2 lines
Documentation/CodingGuidelines For C programs: · line 419
Quoted 2 lines
Documentation/CodingGuidelines +2
-0+ use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.)
Patch update to follow. Thanks.
- Emily
PATCH v4 1/1 doc: hint about GIT_DEBUGGER in CodingGuidelines
In reply to Emily ShafferWe check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented).
--- Documentation/CodingGuidelines | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/CodingGuidelines +6 -0
@@ -412,6 +412,12 @@ For C programs: must be declared with "extern" in header files. However, function declarations should not use "extern", as that is already the default. + - You can launch gdb around your program using the shorthand GIT_DEBUGGER. + Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or + run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to + use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" + ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + For Perl programs: - Most of the C guidelines above apply.
Signature · 1 line
2.22.0.rc1.257.g3120a18244-goog