Skip to content

Commit b21cb8a

Browse files
chrisyarbroughchrisyarbrough
committed
Add ZSH completion command (and setup instructions)
1 parent 355fa2d commit b21cb8a

4 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ A terminal command to open Unity projects quickly from the command line.
2929
| `create <directory> [version]` | Creates a new empty Unity project in the directory. |
3030
| `upm-git-url [path]` | Generates a package git URL for Unity Package Manager from a project. |
3131
| `hub` | Executes Unity Hub interactively or with additional CLI arguments. |
32+
| `completion [shell]` | Generates shell completion scripts (supports ZSH). |
3233

3334
`path` can be a ProjectVersion.txt file or a directory (searches up and down for projects).
3435
If a directory contains multiple Unity projects, an interactive prompt will request a single selection.
@@ -114,6 +115,49 @@ Press the ESC key to cancel the prompt.
114115
If `fzf` is not installed, the built-in search will be used as a fallback.
115116
Press CTRL + C to cancel the prompt. Known bug: This will leave the console cursor hidden.
116117

118+
### Shell Completion (Optional)
119+
120+
`ucll` supports generating shell completion scripts to enable tab completion for commands and options.
121+
122+
#### ZSH Setup
123+
124+
1. **Generate the completion script:**
125+
```shell
126+
ucll completion > ~/.zsh/completions/_ucll
127+
```
128+
129+
2. **Enable completions in your `~/.zshrc` (if not already configured):**
130+
```shell
131+
# Add completion directory to fpath
132+
fpath=(~/.zsh/completions $fpath)
133+
134+
# Initialize completion system
135+
autoload -Uz compinit && compinit
136+
```
137+
138+
3. **Reload your shell:**
139+
```shell
140+
exec zsh
141+
```
142+
Or simply open a new terminal window.
143+
144+
#### Usage
145+
146+
Once installed, you can use tab completion:
147+
148+
- `ucll <TAB>` - Shows all available commands
149+
- `ucll open <TAB>` - Shows options like `--favorite`, `--code-editor`, `--dry-run`
150+
- `ucll version-usage <TAB>` - Shows options like `--plaintext`, `--modules`
151+
152+
#### Updating Completions
153+
154+
When you update `ucll` or new commands are added, regenerate the completion script:
155+
156+
```shell
157+
ucll completion > ~/.zsh/completions/_ucll
158+
exec zsh
159+
```
160+
117161
### Unity Hub
118162

119163
- Ensure version 3.15.4 or newer is installed (https://unity.com/download)

‎src/ucll/Commands/Completion/CompletionCommand.cs‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
internal class CompletionCommand : BaseCommand<CompletionSettings>
2+
{
3+
protected override int ExecuteImpl(CompletionSettings settings)
4+
{
5+
if (settings.Shell.Equals("zsh", StringComparison.OrdinalIgnoreCase))
6+
{
7+
Console.WriteLine(GenerateZshCompletion());
8+
return 0;
9+
}
10+
11+
WriteError($"Unsupported shell: {settings.Shell}. Currently only 'zsh' is supported.");
12+
return 1;
13+
}
14+
15+
private static string GenerateZshCompletion()
16+
{
17+
return """
18+
#compdef ucll
19+
20+
_ucll() {
21+
local -a commands
22+
commands=(
23+
'open:Open Unity Editor for a project search path or via recent projects prompt'
24+
'create:Create a new Unity project'
25+
'project-path:Get Unity project root directory from search path or via recent projects prompt'
26+
'editor-revision:Get revision for Unity version'
27+
'editor-path:Get installation path for Unity version'
28+
'editor-modules:List installed modules for Unity version'
29+
'project-version:Get Unity version from project search directory or ProjectVersion.txt'
30+
'version-usage:List installed Unity Editor versions and indicate which ones are used by projects'
31+
'projects-using:Find all projects that use a specific Unity version'
32+
'install:Install Unity Editor version'
33+
'install-missing:Install all Unity versions that are used by projects but not currently installed'
34+
'uninstall-unused:Uninstall all Unity versions that are not used by any projects'
35+
'upm-git-url:Generate a git URL for Unity Package Manager from a Unity project'
36+
'hub:Execute Unity Hub interactively or with additional CLI arguments'
37+
'completion:Generate shell completion scripts'
38+
)
39+
40+
_arguments -C \
41+
'1: :->command' \
42+
'*::arg:->args'
43+
44+
case "$state" in
45+
command)
46+
_describe 'command' commands
47+
;;
48+
args)
49+
case $words[1] in
50+
open)
51+
_arguments \
52+
'(-f --favorite --favorites)'{-f,--favorite,--favorites}'[Use favorite projects only]' \
53+
'(-c --code-editor)'{-c,--code-editor}'[Open the solution file in the default code editor]' \
54+
'--dry-run[Show what would be executed without actually running mutating commands]'
55+
;;
56+
create)
57+
_arguments \
58+
'(-m --minimal)'{-m,--minimal}'[Creates a bare-minimum project (fast)]' \
59+
'--dry-run[Show what would be executed without actually running mutating commands]' \
60+
'1:project path:_directories' \
61+
'2:version:'
62+
;;
63+
project-path)
64+
_arguments \
65+
'(-f --favorite --favorites)'{-f,--favorite,--favorites}'[Use favorite projects only]'
66+
;;
67+
editor-revision)
68+
_arguments \
69+
'1:version:'
70+
;;
71+
editor-path)
72+
_arguments \
73+
'1:version:'
74+
;;
75+
editor-modules)
76+
_arguments \
77+
'1:version:'
78+
;;
79+
project-version)
80+
_arguments \
81+
'(-f --favorite --favorites)'{-f,--favorite,--favorites}'[Use favorite projects only]'
82+
;;
83+
version-usage)
84+
_arguments \
85+
'(-p --plaintext --plain)'{-p,--plaintext,--plain}'[Output in a simple machine-parseable format]' \
86+
'(-m --modules)'{-m,--modules}'[Include installed modules for each editor version]'
87+
;;
88+
projects-using)
89+
_arguments \
90+
'1:version:'
91+
;;
92+
install)
93+
_arguments \
94+
'--dry-run[Show what would be executed without actually running mutating commands]' \
95+
'1:version:' \
96+
'2:changeset:'
97+
;;
98+
install-missing)
99+
_arguments \
100+
'--dry-run[Show what would be executed without actually running mutating commands]'
101+
;;
102+
uninstall-unused)
103+
_arguments \
104+
'--dry-run[Show what would be executed without actually running mutating commands]'
105+
;;
106+
upm-git-url)
107+
_arguments \
108+
'(-f --favorite --favorites)'{-f,--favorite,--favorites}'[Use favorite projects only]'
109+
;;
110+
hub)
111+
# Hub command accepts arbitrary arguments, no specific completion
112+
;;
113+
completion)
114+
_arguments \
115+
'1:shell:(zsh)'
116+
;;
117+
esac
118+
;;
119+
esac
120+
}
121+
122+
_ucll
123+
""";
124+
}
125+
}

‎src/ucll/Commands/Completion/CompletionSettings.cs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
using System.ComponentModel;
2+
3+
internal class CompletionSettings : CommandSettings
4+
{
5+
[CommandArgument(0, "[shell]")]
6+
[Description("Shell type to generate completions for (currently only 'zsh' is supported)")]
7+
[DefaultValue("zsh")]
8+
public string Shell { get; init; } = "zsh";
9+
}

‎src/ucll/Program.cs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,11 @@
101101
.WithDescription("Execute Unity Hub interactively or with additional CLI arguments")
102102
.WithExample("hub")
103103
.WithExample("hub", "-- --headless help");
104+
105+
config.AddCommand<CompletionCommand>("completion")
106+
.WithDescription("Generate shell completion scripts")
107+
.WithExample("completion")
108+
.WithExample("completion", "zsh");
104109
});
105110

106111
return app.Run(args);

0 commit comments

Comments
 (0)