| Message ID | 20190517204826.45308-1-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: hint about GIT_DEBUGGER | expand |
Hi Emily, On Fri, May 17, 2019 at 3:40 PM Emily Shaffer <emilyshaffer@google.com> wrote: > > 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. Thanks for working on this. > Signed-off-by: Emily Shaffer <emilyshaffer@google.com> > --- > Maybe this isn't the right place for this patch. But right now git grep > reveals that GIT_DEBUGGER is completely undocumented. Does 'git log --grep=GIT_DEBUGGER' count? ;-) > 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(+) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 32210a4386..e17cd75b50 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -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] > > + - 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). 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 > > Elijah
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 32210a4386..e17cd75b50 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -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.
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. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> --- 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(+)