From 174443ed3aa5adbc962d46c23e13dbd3794811fb Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Mon, 27 May 2024 10:30:47 +1000 Subject: [PATCH 1/3] Documentation: alias: rework notes into points There are a number of caveats when using aliases. Rather than stuffing them all together in a paragraph, let's separate them out into individual points to make it clearer what's going on. Signed-off-by: Ian Wienand Signed-off-by: Junio C Hamano --- Documentation/config/alias.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt index 01df96fab3..40851ef429 100644 --- a/Documentation/config/alias.txt +++ b/Documentation/config/alias.txt @@ -21,8 +21,9 @@ If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining `alias.new = !gitk --all --not ORIG_HEAD`, the invocation `git new` is equivalent to running the shell command -`gitk --all --not ORIG_HEAD`. Note that shell commands will be -executed from the top-level directory of a repository, which may -not necessarily be the current directory. -`GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` -from the original current directory. See linkgit:git-rev-parse[1]. +`gitk --all --not ORIG_HEAD`. Note: ++ +* Shell commands will be executed from the top-level directory of a + repository, which may not necessarily be the current directory. +* `GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` + from the original current directory. See linkgit:git-rev-parse[1]. From d35a7436597277d65c84acdc4e951c45c791ea15 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Mon, 27 May 2024 10:30:48 +1000 Subject: [PATCH 2/3] Documentation: alias: add notes on shell expansion When writing inline shell for shell-expansion aliases (i.e. prefixed with "!"), there are some caveats around argument parsing to be aware of. This series of notes attempts to explain what is happening more clearly. Signed-off-by: Ian Wienand Signed-off-by: Junio C Hamano --- Documentation/config/alias.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt index 40851ef429..2c5db0ad84 100644 --- a/Documentation/config/alias.txt +++ b/Documentation/config/alias.txt @@ -27,3 +27,17 @@ it will be treated as a shell command. For example, defining repository, which may not necessarily be the current directory. * `GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` from the original current directory. See linkgit:git-rev-parse[1]. +* Shell command aliases always receive any extra arguments provided to + the Git command-line as positional arguments. +** Care should be taken if your shell alias is a "one-liner" script + with multiple commands (e.g. in a pipeline), references multiple + arguments, or is otherwise not able to handle positional arguments + added at the end. For example: `alias.cmd = "!echo $1 | grep $2"` + called as `git cmd 1 2` will be executed as 'echo $1 | grep $2 + 1 2', which is not what you want. +** A convenient way to deal with this is to write your script + operations in an inline function that is then called with any + arguments from the command-line. For example `alias.cmd = "!c() { + echo $1 | grep $2 ; }; c" will correctly execute the prior example. +** Setting `GIT_TRACE=1` can help you debug the command being run for + your alias. From 291ef5b61c569ca9d40100fec6ab16dfd65c9a32 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Mon, 27 May 2024 10:30:49 +1000 Subject: [PATCH 3/3] run-command: show prepared command This adds a trace point in start_command so we can see the full command invocation without having to resort to strace/code inspection. For example: $ GIT_TRACE=1 git test foo git.c:755 trace: exec: git-test foo run-command.c:657 trace: run_command: git-test foo run-command.c:657 trace: run_command: 'echo $*' foo run-command.c:749 trace: start_command: /bin/sh -c 'echo $* "$@"' 'echo $*' foo Prior changes have made the documentation around the internals of the alias command execution clearer, but I have still found this detailed view of the aliased command being run helpful for debugging purposes. A test case is added to ensure the full command output is present in the execution flow. Signed-off-by: Ian Wienand Signed-off-by: Junio C Hamano --- run-command.c | 3 +++ t/t0014-alias.sh | 11 +++++++++++ 2 files changed, 14 insertions(+) diff --git a/run-command.c b/run-command.c index 1b821042b4..31b20123d8 100644 --- a/run-command.c +++ b/run-command.c @@ -746,6 +746,8 @@ fail_pipe: goto end_of_spawn; } + trace_argv_printf(&argv.v[1], "trace: start_command:"); + if (pipe(notify_pipe)) notify_pipe[0] = notify_pipe[1] = -1; @@ -913,6 +915,7 @@ end_of_spawn: else if (cmd->use_shell) cmd->args.v = prepare_shell_cmd(&nargv, sargv); + trace_argv_printf(cmd->args.v, "trace: start_command:"); cmd->pid = mingw_spawnvpe(cmd->args.v[0], cmd->args.v, (char**) cmd->env.v, cmd->dir, fhin, fhout, fherr); diff --git a/t/t0014-alias.sh b/t/t0014-alias.sh index 95568342be..854d59ec58 100755 --- a/t/t0014-alias.sh +++ b/t/t0014-alias.sh @@ -44,4 +44,15 @@ test_expect_success 'run-command formats empty args properly' ' test_cmp expect actual ' +test_expect_success 'tracing a shell alias with arguments shows trace of prepared command' ' + cat >expect <<-EOF && + trace: start_command: SHELL -c ${SQ}echo \$* "\$@"${SQ} ${SQ}echo \$*${SQ} arg + EOF + git config alias.echo "!echo \$*" && + env GIT_TRACE=1 git echo arg 2>output && + # redact platform differences + sed -n -e "s/^\(trace: start_command:\) .* -c /\1 SHELL -c /p" output >actual && + test_cmp expect actual +' + test_done