|
| 1 | +bin.name = "rustup" |
| 2 | +args = ["completions","--help"] |
| 3 | +stdout = """ |
| 4 | +rustup-completions |
| 5 | +Generate tab-completion scripts for your shell |
| 6 | +
|
| 7 | +USAGE: |
| 8 | + rustup completions [ARGS] |
| 9 | +
|
| 10 | +FLAGS: |
| 11 | + -h, --help Prints help information |
| 12 | +
|
| 13 | +ARGS: |
| 14 | + <shell> [possible values: zsh, bash, fish, powershell, elvish] |
| 15 | + <command> [possible values: rustup, cargo] |
| 16 | +
|
| 17 | +DISCUSSION: |
| 18 | + Enable tab completion for Bash, Fish, Zsh, or PowerShell |
| 19 | + The script is output on `stdout`, allowing one to re-direct the |
| 20 | + output to the file of their choosing. Where you place the file |
| 21 | + will depend on which shell, and which operating system you are |
| 22 | + using. Your particular configuration may also determine where |
| 23 | + these scripts need to be placed. |
| 24 | +
|
| 25 | + Here are some common set ups for the three supported shells under |
| 26 | + Unix and similar operating systems (such as GNU/Linux). |
| 27 | +
|
| 28 | + BASH: |
| 29 | +
|
| 30 | + Completion files are commonly stored in `/etc/bash_completion.d/` for |
| 31 | + system-wide commands, but can be stored in |
| 32 | + `~/.local/share/bash-completion/completions` for user-specific commands. |
| 33 | + Run the command: |
| 34 | +
|
| 35 | + $ mkdir -p ~/.local/share/bash-completion/completions |
| 36 | + $ rustup completions bash >> ~/.local/share/bash-completion/completions/rustup |
| 37 | +
|
| 38 | + This installs the completion script. You may have to log out and |
| 39 | + log back in to your shell session for the changes to take effect. |
| 40 | +
|
| 41 | + BASH (macOS/Homebrew): |
| 42 | +
|
| 43 | + Homebrew stores bash completion files within the Homebrew directory. |
| 44 | + With the `bash-completion` brew formula installed, run the command: |
| 45 | +
|
| 46 | + $ mkdir -p $(brew --prefix)/etc/bash_completion.d |
| 47 | + $ rustup completions bash > $(brew --prefix)/etc/bash_completion.d/rustup.bash-completion |
| 48 | +
|
| 49 | + FISH: |
| 50 | +
|
| 51 | + Fish completion files are commonly stored in |
| 52 | + `$HOME/.config/fish/completions`. Run the command: |
| 53 | +
|
| 54 | + $ mkdir -p ~/.config/fish/completions |
| 55 | + $ rustup completions fish > ~/.config/fish/completions/rustup.fish |
| 56 | +
|
| 57 | + This installs the completion script. You may have to log out and |
| 58 | + log back in to your shell session for the changes to take effect. |
| 59 | +
|
| 60 | + ZSH: |
| 61 | +
|
| 62 | + ZSH completions are commonly stored in any directory listed in |
| 63 | + your `$fpath` variable. To use these completions, you must either |
| 64 | + add the generated script to one of those directories, or add your |
| 65 | + own to this list. |
| 66 | +
|
| 67 | + Adding a custom directory is often the safest bet if you are |
| 68 | + unsure of which directory to use. First create the directory; for |
| 69 | + this example we'll create a hidden directory inside our `$HOME` |
| 70 | + directory: |
| 71 | +
|
| 72 | + $ mkdir ~/.zfunc |
| 73 | +
|
| 74 | + Then add the following lines to your `.zshrc` just before |
| 75 | + `compinit`: |
| 76 | +
|
| 77 | + fpath+=~/.zfunc |
| 78 | +
|
| 79 | + Now you can install the completions script using the following |
| 80 | + command: |
| 81 | +
|
| 82 | + $ rustup completions zsh > ~/.zfunc/_rustup |
| 83 | +
|
| 84 | + You must then either log out and log back in, or simply run |
| 85 | +
|
| 86 | + $ exec zsh |
| 87 | +
|
| 88 | + for the new completions to take effect. |
| 89 | +
|
| 90 | + CUSTOM LOCATIONS: |
| 91 | +
|
| 92 | + Alternatively, you could save these files to the place of your |
| 93 | + choosing, such as a custom directory inside your $HOME. Doing so |
| 94 | + will require you to add the proper directives, such as `source`ing |
| 95 | + inside your login script. Consult your shells documentation for |
| 96 | + how to add such directives. |
| 97 | +
|
| 98 | + POWERSHELL: |
| 99 | +
|
| 100 | + The powershell completion scripts require PowerShell v5.0+ (which |
| 101 | + comes with Windows 10, but can be downloaded separately for windows 7 |
| 102 | + or 8.1). |
| 103 | +
|
| 104 | + First, check if a profile has already been set |
| 105 | +
|
| 106 | + PS C:/> Test-Path $profile |
| 107 | +
|
| 108 | + If the above command returns `False` run the following |
| 109 | +
|
| 110 | + PS C:/> New-Item -path $profile -type file -force |
| 111 | +
|
| 112 | + Now open the file provided by `$profile` (if you used the |
| 113 | + `New-Item` command it will be |
| 114 | + `${env:USERPROFILE}/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` |
| 115 | +
|
| 116 | + Next, we either save the completions file into our profile, or |
| 117 | + into a separate file and source it inside our profile. To save the |
| 118 | + completions into our profile simply use |
| 119 | +
|
| 120 | + PS C:/> rustup completions powershell >> |
| 121 | +${env:USERPROFILE}/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1 |
| 122 | +
|
| 123 | + CARGO: |
| 124 | +
|
| 125 | + Rustup can also generate a completion script for `cargo`. The script output |
| 126 | + by `rustup` will source the completion script distributed with your default |
| 127 | + toolchain. Not all shells are currently supported. Here are examples for |
| 128 | + the currently supported shells. |
| 129 | +
|
| 130 | + BASH: |
| 131 | +
|
| 132 | + $ rustup completions bash cargo >> ~/.local/share/bash-completion/completions/cargo |
| 133 | +
|
| 134 | + ZSH: |
| 135 | +
|
| 136 | + $ rustup completions zsh cargo > ~/.zfunc/_cargo |
| 137 | +""" |
| 138 | +stderr = "" |
0 commit comments