ALSO I've tested this on windows; it works but sh is, of course, not there. I'm not sure what the recommended way of doing this in Windows is so I'll research that next week.

Thanks for such a great writeup @vilmibm!

! character

I’m leaning more towards something like the —external flag. The main reason is it makes things very obvious when you read it.

$ gh alias set igrep '!gh issue list | grep $1' vs $ gh alias set --external igrep "gh issue list | grep $1"

The ! is handy, but it feels a little too magical to me. Naming it something like —shell advanced or —complex would also make sense to me.

quote madness

I think always wrapping the command in $SHELL -c makes a lot of sense. Especially if we can detect their default shell and put it in the config. It’s magical on the code side, but I think it matches expectations the use will have.

Multiline input

I don’t have strong opinions on this right now. Seeing some examples where it would make the aliases better or easier to use would be 👍

Thank you for writing this up @vilmibm!

• is the ! character ok for signalling to gh that the user wants an external alias?

We original set out to support quote-less syntax defining aliases, e.g. gh alias set foo issue list --foo. If we introduce ! into the syntax, the quote-less approach will no longer work for shells like bash. Since we don't really advertise quote-less support, I wonder whether it makes sense to keep it?

Moreover, the ! character is special in yaml too, so if someone manually adds an alias to their aliases: config file section and doesn't properly quote or escape the ! character, their config file will suddenly trigger yaml-parsing errors.

I would really like us to avoid !. These are also ruled out due to their specialness in yaml: #, &, *, @, %. That leaves us with: ^, :, +. These characters are safer both in yaml and in shell.

There is also an option to not require any special character prefix, but to detect when shell features such as piping and redirection are used in an alias and automatically execute it though a shell interpreter. But this approach might be brittle.

• should we wrap all external aliases in sh -c "<expansion>"?

I had expected that all "external" aliases are executed by sh so that they can support syntax such as piping and output redirection. I have understood that this was the entire point of "external" aliases.

• should we worry about multi-line input at this point?

No, I don't think so!

That leaves us with: ^, :, +. These characters are safer both in yaml and in shell.

None of these really felt right; I like that ! at least has a vaguely consistent meaning in the CLI world of "call something."

As you point out we lose the quote-less behavior either way when a user is adding shell aliases; I think a -e/--external flag is a good place to start given that observation.

There is also an option to not require any special character prefix, but to detect when shell features such as piping and redirection are used in an alias and automatically execute it though a shell interpreter. But this approach might be brittle.

I thought about this and was also worried it would be brittle, but I wonder how often I, <, and > really appear in arguments? A middle ground might be detecting that and then suggesting --external to the user.

I had expected that all "external" aliases are executed by sh so that they can support syntax such as piping and output redirection. I have understood that this was the entire point of "external" aliases.

My baseline for external aliases is that whatever right hand side is provided is passed to exec.Command; not that we run it through sh -c. I was replicating git's example which requires explicit use of $SHELL -c "..." to support redirection and composition.

It sounds like you are in favor of passing everything through a shell implicitly, @mislav ; do you agree that having shell be configurable makes sense in that case (with a default of $SHELL)?

I propose this kind of experience which still doesn't feel perfect but I think will cover most cases:

$ gh alias set co 'pr checkout'
Added alias.

$ gh alias set igrep 'issue list | grep $1'
! It looks like you're trying to use a command external to gh. Did you want --external?
Added alias.

$ gh igrep bug
# ... shows issue list output with no composition ... 

$ gh alias set -e igrep 'issue list | grep $1'
! "issue" command not found on path
Updated alias.

$ gh igrep bug
issue: command not found

$ gh alias set -e igrep 'gh issue list | grep $1'
Updated alias.

$ gh igrep bug
# ... shows list output with grepping as expected ...

I chatted with @ampinsk about this and we decided to investigate the feasibility of letting a user not have to think about external vs. internal aliases.

We'll try and detect when a alias ought to be run through $SHELL (ie presence of certain characters, command that isn't a gh subcommand but is on $PATH) and then act accordingly. (something @mislav and I were discussing as interesting but possibly too brittle).

I'll take a shot at this so we can play with it and see how it feels in practice.

@mislav @ampinsk I got implicit internal/external aliases working as discussed above. It was easier to just talk through it so I made a 6 minute video demo:

https://www.youtube.com/watch?v=lsw-tzcJmmU

If y'all like it I'll get the code cleaned up and tested, just let me know!~

@vilmibm This is SO cool to see - I loved it all and really appreciate how much thought you and @ampinsk have put into it. 💖

The one question I had was about the warning combined with creating the alias. I wonder if a compromise there would be the warning and then a prompt with something like: "Would you like to create this alias? (Y/n)" It feels strange to me to have to go back and delete something just because of a typo, but maybe y'all already discussed that.

@billygriffin I'm fine with making it a prompt! we did not explicitly discuss it.

My baseline for external aliases is that whatever right hand side is provided is passed to exec.Command; not that we run it through sh -c.

I see. I had understood that all git's "shell" aliases are implicitly evaluated through a shell even if sh -c '...' was not used in the alias. In fact, that's the behavior that I'm seeing:

$ git config alias.foo '!type echo && echo $SHELL || echo ERROR >&2; echo "${USER#mi}"; echo arg:'
$ git foo bar
echo is a shell builtin
/bin/bash
slav
arg: bar

Even though I didn't use sh -c or $SHELL -c, the alias seems to have been evaluated in a shell, as evident by expansions of different shell syntaxes such as redirection and chaining. The extra argument bar was appended at the end.

I was replicating git's example which requires explicit use of $SHELL -c "..." to support redirection and composition.

From what I understand, explicit usage of sh -c or $SHELL -c inside a shell alias only adds value if we are using it to inject positional arguments somewhere in the middle of the command instead of at the end:

$ git config alias.foo '!echo 2:$2 1:$1 DONE'; git foo one two
2:two 1:one DONE one two

$ git config alias.foo '!sh -c "echo 2:\\$2 1:\\$1 DONE"'; git foo one two
2:two 1:one DONE

I got implicit internal/external aliases working as discussed above. It was easier to just talk through it so I made a 6 minute video demo:

Thank you for recording this! It really communicates your goals and the potential approach well.

Since external aliases can potentially contain complex syntax, I'm wary of trying to auto-detect anything within them, such as looking at the first word and determining whether it's a gh command or an external utility somewhere in the person's PATH. I'm 4/5 on how strongly I feel that any attempt of auto-detection make ourselves vulnerable to all kinds of edge-cases which would arise when people copy-paste their aliases between different machines, from each other, and when their PATH changes between when they've recorded the alias and when they execute it.

One thing I really value about git's ! aliases is that they are explicitly marked and always guaranteed to work the same: whatever alias is configured will always be passed verbatim through a shell interpreter. Their non-magicness is a feature in it of itself.

I realize that I was the one who casually suggested auto-detection 🙈 Now that I've considered it from different angles and heard your exploration and thoughts on it, I'm much more leaning to a system where regular and "external" aliases are strongly delineated.

I had understood that all git's "shell" aliases are implicitly evaluated through a shell even if sh -c '...' was not used in the alias.

Ah, I got confused; I saw the explicit use in some documentation and assumed it was required without testing it.

Your concerns with the implicit approach are valid. My big concern is the inconsistency around specifying gh; I felt very unsure about the automagic I was doing around that. It went against my usual impulses (explicitness, nonmagic) but I was pleasantly surprised by how natural actually writing the aliases felt.

I don't think I have strongly held opinions in any direction aside from now agreeing we should avoid !. After talking to Amanda I don't like -e/--external much, either, but I think -s/--shell might work?

I'll implement that and we can all make a final decision.

(cc @ampinsk )

Ok; now things work like this:

$ ghd alias set prs 'pr status'
- Adding alias for prs: pr status
✓ Added alias.

$ ghd alias set igrep '!gh issue list -L100 | grep $1'
- Adding alias for igrep: !gh issue list -L100 | grep $1
✓ Added alias.

$ ghd alias set --shell checklist 'ghd issue list --label=$1 | sed "s/^/- [ ] /" > checklist.md'
- Adding alias for checklist: ghd issue list --label=$1 | sed "s/^/- [ ] /" > checklist.md
✓ Added alias.

$ ghd alias set -s echo echo
- Adding alias for echo: echo
✓ Added alias.

$ ghd alias list
bugs:       issue list --label=bug
checklist:  !ghd issue list --label=$1 | sed "s/^/- [ ] /" > checklist.md
clone:      repo clone
co:         pr checkout
echo:       !echo
igrep:      !gh issue list -L100 | grep $1
prs:        pr status

@mislav @ampinsk if this works for y'all I'll get started on tests.

@vilmibm That looks great ✨

I'm noticing that alias set '!...' and alias set --shell '...' are equivalents in functionality. Would we consider only supporting one of these syntaxes for ease of documentation? My vote would be towards alias set --shell because of its explicitness.

Would we consider only supporting one of these syntaxes for ease of documentation?

Since we're going to prepend a ! for aliases created via --shell it seemed confusing to not allow a user to prepend it themselves; that said, I'd be comfortable not documenting creating an alias with !. Does that make sense?

Since we're going to prepend a ! for aliases created via --shell it seemed confusing to not allow a user to prepend it themselves; that said, I'd be comfortable not documenting creating an alias with !

Ah that makes perfect sense. Thank you!

@mislav Caught up on the feedback as well as what we discussed in our call.

@mislav The windows support is ready for review now.

I know it's tricky to support sh on Windows, but maybe we could find a way as followup, and until then not support shell aliases executing for Windows users unless they have sh interpreter in their PATH?

I don't like this approach. It feels almost rude to windows users and reminds me of the Cygwin days ("You can run this tool designed for unix, sure, but you need to install and manage this other runtime to do so").

Windows has decent command line tooling now and I think it's worth the extra effort and code to embrace that.

That said -- if we're requiring git to be installed, I believe that means we can rely on bash being installed. Is that a decent compromise? I'm trying to avoid a situation where Windows users do not get access to a feature until they take some manual step on their own (outside of the steps required to simply install gh).

I'm trying to avoid a situation where Windows users do not get access to a feature until they take some manual step on their own

Absolutely agreed. Ideally, gh should just work out of the box (provided git is installed) on every platform.

On Windows, if someone installed Git for Windows, there's a large chance that they have the bash interpreter installed. We could use bash --posix as a mechanism to execute shell aliases over.

Switching to gitbash is not as simple we expected.

While we can run aliases through it and call the utilities that gitbash provides, gitbash knows nothing about gh. We can get the path to the executable via os.Executable() but, being windows, it's in C:\Users\...\gh.exe format, which gitbash cannot parse. Short of manually translating the path (which isn't just a straight substitution: drive letters are mapped to /mnt/C/... and we'd have to translate that too) I'm not sure of a reliable way to inject gh into gitbash's PATH.

This all works for git on windows since gitbash is specifically tailored to, well, run git. It's not tailored to run gh and I think forcing it to do so is a bad idea.

I spent the last part of my day attempting to make argument passing more robust when using pwsh. I have learned a tremendous amount about how powershell parses things and have a few leads on a more robust way to pass arguments but nothing solid yet; I am pessimistic that I can do any better than layers of escaping.

After my day of disappointing research I think we should give up on gitbash or any hope for having aliases share-able between windows and !windows. I'll put another few hours of research into improving argument passing for powershell but suspect that what is in 0459eaf is the best I'll be able to come up with for this first attempt.

I'm not sure of a reliable way to inject gh into gitbash's PATH.

I'm thinking that we might not need to change PATH at all. Both Git for Windows and GitHub CLI installers add the respective binaries to the system PATH. We can assume that this has happened and that unqualified git and gh will always be available for execution no matter what the context (cmd.exe, PowerShell, Git Bash, Cygwin, etc.).

Here is what I propose for executing shell aliases:

1. Use sh if found in the PATH. This covers: macOS, Linux, Git Bash on Windows, Cygwin, WSL.

2. If sh was unavailable, then try to find it in the following location: GIT_EXE_DIR\..\bin\sh, where GIT_EXE_DIR is found by locating git.exe in PATH. This will resolve to something like C:\Program Files\Git\bin\sh, where Git for Windows puts both sh and bash executables. (Surprisingly, C:\Program Files\Git\bin itself is not in PATH.)

3. If sh is still unavailable, then we print a message to the user that shell aliases cannot be executed in their current setup.

Basically, we would do from Go the equivalent of this PowerShell invocation, which works for me with no extra setup apart from installing Git for Windows and GitHub CLI:

& "C:\Program Files\Git\bin\sh" -c "gh help | grep gist"

Do you think this would be feasible and would serve our users well?

I might be missing something but I don't see how

& "C:\Program Files\Git\bin\sh" -c "gh help | grep gist"

could work. sh does not know how to run gh and producing an absolute path to gh for sh to use is difficult for the reasons I stated.

sh does not know how to run gh

I see! For me, when sh executes it somehow already has gh in its PATH, since the parent process also had it in its PATH. But to be honest, I don't know how its filesystem path translation works on the boundary from PowerShell → sh nor why you don't have the same experience. I will try to look into this deeper.

I haven't dug into the why but I at least see how we're getting different results, here.

bash -c 'gh issue list => bash runs, gh not found
sh -c 'gh issue list => windows can't find sh
C:\Program Files\Git\bin\sh -c 'gh issue list' => works fine
C:\Program Files\Git\bin\bash -c 'gh issue list' => works fine

I'm guessing that when I just run bash there is some kind of shim that alters the path.

I will incorporate calling sh via an absolute path into the code and see how that works. Thanks for helping investigate this.

Based on our combined investigation, I finally have shell aliases working on Windows via gitbash.

PS C:\Users\vilmi\src\cli\cmd\gh> .\gh.exe alias set -s sigh 'gh issue list --label $1 | grep $2'
PS C:\Users\vilmi\src\cli\cmd\gh> .\gh.exe sigh epic alias                                                                                                       [C:\Program Files\Git\bin\sh.exe -c gh issue list --label $1 | grep $2 -- epic alias]                                                                                                                                                                                                                                                                                                                              Showing 2 of 2 issues in cli/cli that match your search                                                                                                                                                                                                                                                                           939     Alias support phase 2   aliases, epic   about 1 month ago