[#133] Added shell completion

[MitchellBerend]

Resolves #133

This pr aims to add a tab completion script so users don't have to remember every command if they want to experiment with config options.

Additional tasks

• Documentation for changes provided/changed
• Tests added
• Updated CHANGELOG.md

[chshersh]

@MitchellBerend Just to have TL;DR: does it mean that completion doesn't work if the binary has the name tool and not tool-sync?

[MitchellBerend]

It does, the way it is implemented in the pr right now it gets the name automatically. There is an easy way to override this with tool (or anything for that matter)

[chshersh]

@MitchellBerend That's great to hear!

I see that this PR is still draft. Would you prefer to wait for the clap-4.0 upgrade before we could merge this one?

[MitchellBerend]

Yes I would, I put a blocked tag on the issue itself. I don't think i can put labels on prs but consider this one blocked until #136 is resolved.

[SanchithHegde]

@MitchellBerend Sorry to have kept you waiting, I've opened #137 for the clap-4.0 upgrade.

[MitchellBerend]

@SanchithHegde don't worry about it, Im at a convention anyway 😅.

[MitchellBerend]

@chshersh In my opinion we should have a consistent naming convention throughout the entire code base. I think #130 would also benefit from that since there would be a clear way to prefix environment variables.

[MitchellBerend]

There is an issue with the help text of the current completion command. Because some lines are indented they get interpreted as rust code and as such they will be ran through the docs tests. Since those indented lines are (mostly) bash scripts they don't pass docs tests in ci.

There is a config option (#[cfg(not(doctest))]) that disables the doc test for an entire module and since this issue is contained in the src/config/cli.rs file this would work, but I get weird compiler errors trying to add this.

Im not sure if I like the way the formatting looks when the indentation are removed. I added ` around the commands to make it a little clearer but this still looks kind of like a wall of text to me.

There is an issue filed on the main rust repo for this already.

[MitchellBerend]

Sample output:

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion --help 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion --help`
Generate shell completion scripts for GitHub CLI commands.

You will need to set up completions manually, follow the instructions below. The exact config file locations might vary based on your system. Make sure to restart your shell before testing whether completions are working.

### bash

First, ensure that you install `bash-completion` using your package manager.

After, add this to your `~/.bash_profile`:

`eval "$(tool completion bash)"`

### zsh

Generate a `_tool` completion script and put it somewhere in your `$fpath`:

`tool completion zsh > /usr/local/share/zsh/site-functions/_tool`

Ensure that the following is present in your `~/.zshrc`:

`autoload -U compinit` `compinit -i`

Zsh version 5.7 or later is recommended.

### fish

Generate a `tool.fish` completion script:

`tool completion fish > ~/.config/fish/completions/tool.fish`

### PowerShell

Open your profile script with:

`mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue` `notepad $profile`

Add the line and save the file:

`Invoke-Expression -Command $(tool completion powershell | Out-String)`

Usage: tool completion <SHELL>

Arguments:
  <SHELL>
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help
          Print help information (use `-h` for a summary)

[chshersh]

@MitchellBerend Thanks for writing such detailed progress updates! The issue with doctest is annoying indeed. The solution with backticks sounds like a good trade-off. And thanks a lot for write great help text! 💯

[MitchellBerend]

Sample output of current implementation

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion bash --rename asdfasdf -- $1 > /dev/null 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion bash --rename asdfasdf --`
First, ensure that you install `bash-completion` using your package manager.

After, add this to your `~/.bash_profile`:

`eval "$(asdfasdf completion bash --rename asdfasdf)"`

----------------------------------------------------------------------------------------------------------------------------------------------------------------

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion fish --rename asdfasdf -- $1 > /dev/null 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion fish --rename asdfasdf --`
Generate a `tool.fish` completion script:

`asdfasdf completion fish --rename asdfasdf > ~/.config/fish/completions/asdfasdf.fish`

----------------------------------------------------------------------------------------------------------------------------------------------------------------

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion zsh --rename asdfasdf -- $1 > /dev/null 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion zsh --rename asdfasdf --`
Generate a `_asdfasdf` completion script and put it somewhere in your `$fpath`:
`asdfasdf completion zsh --rename asdfasdf > /usr/local/share/zsh/site-functions/_asdfasdf`

Ensure that the following is present in your `~/.zshrc`:

`autoload -U compinit`

`compinit -i`

----------------------------------------------------------------------------------------------------------------------------------------------------------------

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion powershell --rename asdfasdf -- $1 > /dev/null 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion powershell --rename asdfasdf --`
Open your profile script with:

`mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue`
`notepad $profile`

Add the line and save the file:

`Invoke-Expression -Command $(asdfasdf completion powershell --rename asdfasdf | Out-String)`

----------------------------------------------------------------------------------------------------------------------------------------------------------------

mitchell@mitchell-workstation:~/rust/tool-sync$ cargo run -- completion elvish --rename asdfasdf -- $1 > /dev/null 
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/tool completion elvish --rename asdfasdf --`
This suggestion is missing, if you use this and know how to implement this please file an issue over at https://github.com/chshersh/tool-sync/issues

[chshersh]

This looks super great! 🏆

I have a few suggestions on refactoring, documenting and changing the module structure a bit. But the implementation is superb ✨

[chshersh]

Will it break though? I see that the Shell type has the #[non_exhaustive] pragma. And we also handle all other shells with _.

So, in other words, the compiler won't output any errors if clap_complete adds new shells. They'll simply remain unsupported as now. And people can open new issues to request support for new shells 🙂

[MitchellBerend]

I added that comment to clarify why there is a separate function for a simple match statement. Maybe this should include an error message along the lines of:

This shell type is not implemented yet, please go over to https://github.com/chshersh/tool-sync to file an issue about its implementation.

[chshersh]

Looks amazing! LFG 🚀