feat: support zsh autocomplete

fix: #82

Author: minh

Containerfile

@@ -13,7 +13,10 @@ USER root
 WORKDIR /app/gis
 COPY --from=build /app/gis/target/gis-*.jar target/
 COPY --from=build /app/gis/target/lib target/lib
-RUN native-image -march=compatibility -cp target/gis-*.jar "org.nqm.Gis" --no-fallback -H:IncludeResources=".properties"
+RUN native-image -march=compatibility -cp target/gis-*.jar "org.nqm.Gis" --no-fallback \
+-H:IncludeResources=".properties" \
+-H:IncludeResources="_gis"
+
 RUN mv org.nqm.gis gis
 RUN chmod +x gis
 RUN ./gis --version

README.md

@@ -27,7 +27,7 @@ After the steps above, an executable file named `gis` will be created under proj
 
 ```shell script
 cd gis
-mvn clean package
+mvn clean verify package
 ```
 The executable jar file will be created at `target/gis-<version>.jar`
 
@@ -38,6 +38,14 @@ For more details, just run:
 ./gis --help
 ```
 
+Generate completion for zsh:
+```
+./gis completion --directory ${fpath[1]}
+```
+Reload your zsh session, we can now press `<TAB>` for autocomplete.
+
+Currently gis only support zsh for completion.
+
 # Config
 
 Gis will read config from file at `~/.config/gis.config`

src/main/java/org/nqm/Gis.java

@@ -5,6 +5,7 @@
 import org.nqm.config.GisLog;
 import org.nqm.exception.GisException;
 import picocli.CommandLine;
+import picocli.AutoComplete.GenerateCompletion;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.IExecutionExceptionHandler;
 import picocli.CommandLine.Option;
@@ -13,6 +14,7 @@
 
 @Command(
     name = "gis",
+    subcommands = GenerateCompletion.class,
     description = "Git extension wrapper which supports submodules",
     mixinStandardHelpOptions = true,
     versionProvider = GisVersion.class)
@@ -34,7 +36,12 @@ public static void setVerbose(boolean verbose) {
 
   public static void main(String... args) {
     var gis = new CommandLine(new Gis());
-    gis.setExecutionExceptionHandler(GLOBAL_EXCEPTION_HANLER);
+    gis.setExecutionExceptionHandler(GLOBAL_EXCEPTION_HANLER)
+        .getSubcommands()
+        .get("generate-completion")
+        .getCommandSpec()
+        .usageMessage()
+        .hidden(true);
 
     gis.execute(args.length == 0
         ? new String[] {GIT_STATUS, "--one-line"}

src/main/java/org/nqm/command/GitCommand.java

@@ -4,6 +4,7 @@
 import static org.nqm.command.Wrapper.forEachModuleWith;
 import static org.nqm.config.GisConfig.currentDir;
 import java.io.BufferedReader;
+import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStreamReader;
 import java.nio.file.Files;
@@ -33,6 +34,8 @@ public class GitCommand {
   private static final String ORIGIN = "origin";
   private static final Path TMP_FILE = Path.of("/", "tmp", "gis_fetch" + currentDir().replace("/", "_"));
 
+  static final String GIS_AUTOCOMPLETE_FILE = "_gis";
+
   public static final String GIT_STATUS = "status";
   public static final String HOOKS_OPTION = "--hooks";
 
@@ -93,7 +96,8 @@ void checkoutNewBranch(
       @Parameters(index = "0", paramLabel = "<new_branch_name>",
           description = "branch name") String newBranch,
       @Parameters(paramLabel = "<modules>",
-          description = "Specified modules. If empty, will create for all submodules and root.") String... modules) throws IOException {
+          description = "Specified modules. If empty, will create for all submodules and root.") String... modules)
+      throws IOException {
     if (null == modules || modules.length < 1) {
       forEachModuleDo(CHECKOUT, "-b", newBranch);
       return;
@@ -148,7 +152,8 @@ void remotePruneOrigin() throws IOException {
   }
 
   @Command(name = "local-prune", aliases = "prune")
-  void localPrune(@Parameters(index = "0", paramLabel = "<default branch name>") String branch) throws IOException {
+  void localPrune(@Parameters(index = "0", paramLabel = "<default branch name>") String branch)
+      throws IOException {
     forEachModuleDo("for-each-ref",
         "--merged=%s".formatted(branch),
         "--format=%(refname:short)",
@@ -160,14 +165,16 @@ void localPrune(@Parameters(index = "0", paramLabel = "<default branch name>") S
   }
 
   @Command(name = "stash")
-  void stash(@Option(names = "-pp", description = "pop first stashed changes") boolean isPop) throws IOException {
+  void stash(@Option(names = "-pp", description = "pop first stashed changes") boolean isPop)
+      throws IOException {
     var args = isPop ? new String[] {"stash", "pop"} : new String[] {"stash"};
     forEachModuleDo(args);
   }
 
   @Command(name = "branches")
   void listBranches(
-      @Option(names = "-nn", description = "do not print module name") boolean noPrintModuleName) throws IOException {
+      @Option(names = "-nn", description = "do not print module name") boolean noPrintModuleName)
+      throws IOException {
     var sArgs = Stream.of("for-each-ref", "--format=%(refname:short)", "refs/heads/");
     if (noPrintModuleName) {
       sArgs = Stream.concat(sArgs, Stream.of("--gis-no-print-modules-name"));
@@ -193,6 +200,30 @@ void files() throws IOException {
     forEachModuleDo("diff", "--name-only", "--gis-concat-modules-name");
   }
 
+  @Command(name = "completion", description = "generate an zsh auto completion script")
+  void generateCompletion(
+      @Option(names = "--directory",
+          description = "export completion zsh function to file at specified directory") Path dir)
+      throws IOException {
+    try (var stream = this.getClass().getClassLoader().getResourceAsStream(GIS_AUTOCOMPLETE_FILE)) {
+      var buffer = new BufferedReader(new InputStreamReader(stream));
+      String line = null;
+      if (dir != null) {
+        var file = dir.resolve(GIS_AUTOCOMPLETE_FILE);
+        try (var out = new FileOutputStream(file.toFile())) {
+          while ((line = buffer.readLine()) != null) {
+            out.write(line.getBytes());
+            out.write("%n".formatted().getBytes());
+          }
+        }
+        return;
+      }
+      while ((line = buffer.readLine()) != null) {
+        StdOutUtils.println(line);
+      }
+    }
+  }
+
   private static Stream<String> streamOf(String[] input) {
     return Stream.of(input).map(String::trim).distinct();
   }

src/main/resources/_gis

@@ -0,0 +1,60 @@
+#compdef gis
+compdef _gis gis
+
+function _gis {
+  local line
+  _arguments -C\
+             "1: :(checkout co \
+checkout-branch cb \
+fetch fe \
+fetch-origin fo \
+files \
+init \
+branches \
+local-prune prune \
+pull pu \
+push pus \
+rebase-current-origin ru \
+rebase-origin re \
+remote-prune-origin rpo \
+remove-branch rm \
+stash \
+status st)" \
+             "--help[print help]" \
+             "--version[print gis version]" \
+             "*::arg:->args"
+  case $line[1] in
+    checkout | co | fetch-origin | fo | local-prune | prune | push | pus | rebase-origin | re | remove-branch | rm)
+      _suggest_branches
+      ;;
+    branches)
+      _gis_branches_suggest
+      ;;
+    stash)
+      _gis_stash_suggest
+      ;;
+    status | st)
+      _gis_status_suggest
+      ;;
+  esac
+}
+
+function get_branches {
+  [ -d .git ] && git for-each-ref --format="%(refname:short)" refs/heads refs/remotes
+}
+
+function _suggest_branches {
+  _arguments "1: :($(get_branches))"
+}
+
+function _gis_branches_suggest {
+  _arguments "-nn[do not print module name]"
+}
+
+function _gis_status_suggest {
+  _arguments "--one-line[print result in one line]"
+}
+
+function _gis_stash_suggest {
+  _arguments "-pp[pop first stashed changes]"
+}

src/test/java/org/nqm/command/GitCommandTest.java

@@ -5,6 +5,7 @@
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
+import static org.nqm.command.GitCommand.GIS_AUTOCOMPLETE_FILE;
 import static org.nqm.config.GisConfig.GIT_HOME_DIR;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
@@ -380,4 +381,51 @@ void pushOrigin_OK() throws IOException {
       System.setIn(in);
     }
   }
+
+  @Test
+  void generateCompletionToConsole_OK() throws IOException {
+    // when:
+    gis.generateCompletion(null);
+
+    // then:
+    assertThat(outCaptor).hasToString("""
+        this is a completion
+        script for test gis
+        in zsh.
+        """);
+  }
+
+  @Test
+  void generateCompletionToFile_OK() throws IOException {
+    // when:
+    gis.generateCompletion(tempPath);
+
+    // then:
+    var content = Files.readString(tempPath.resolve(GIS_AUTOCOMPLETE_FILE));
+    assertThat(content).isEqualTo("""
+        this is a completion
+        script for test gis
+        in zsh.
+        """);
+  }
+
+  @Test
+  void generateCompletionToFile_withFileAlreadyExist_shouldOverwrite() throws IOException {
+    // given:
+    var file = tempPath.resolve(GIS_AUTOCOMPLETE_FILE);
+    Files.createFile(file);
+    Files.writeString(file, "this is some existing text");
+
+    // when:
+    gis.generateCompletion(tempPath);
+
+    // then:
+    var content = Files.readString(file);
+    assertThat(content).isEqualTo("""
+        this is a completion
+        script for test gis
+        in zsh.
+        """);
+  }
+
 }

src/test/resources/_gis

@@ -0,0 +1,3 @@
+this is a completion
+script for test gis
+in zsh.