feat: update CLI

Includes refactor, uninstall, fix bad logic and use same logic as the extension for consistency.
Update the docs and add Make command.

Co-authored-by: Copilot <copilot@github.com>

Author: MichaelCurrin

Makefile

@@ -49,6 +49,12 @@ q test-quick:
 	npx tsc -p .
 	npm run test:unit
 
+# Test the CLI tools and their help output.
+cli-help:
+	npx ts-node src/cli/diffIndexGenerate.ts --help
+	npx ts-node src/cli/diffIndexGenerateCommit.ts --help
+	npx ts-node src/cli/generate.ts --help
+
 ### Build
 
 .PHONY: build

README.md

@@ -55,7 +55,7 @@ How to install and run the extension in VS Code.
 
 </div>
 
-If you want to install and run as a CLI tool, see [CLI docs](/docs/cli.md).
+Install the CLI tool quick and easy so you are not tied to the IDE - see [CLI docs](/docs/cli.md).
 
 
 ## Features

bin/uninstall_cli.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Uninstall auto-commit-msg CLI binaries.
+set -e
+
+BINARIES=("acm" "gacm" "auto_commit_msg_generate")
+INSTALL_DIR="$HOME/.local/bin"
+
+rm -f "${BINARIES[@]/#/$INSTALL_DIR/}"
+
+echo "auto-commit-msg binaries uninstalled successfully"

docs/cli.md

@@ -12,20 +12,31 @@ See steps below to setup and run the tool in the CLI.
 
 The pre-built binaries are added to releases on GitHub so you can install them without needing the project or Node.
 
-macOS and Linux:
+Run the command below to install (or update to the latest).
+
+### macOS and Linux
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/MichaelCurrin/auto-commit-msg/refs/heads/master/bin/install_cli.sh | bash
 ```
 
-**Warning this is experimental** Windows PowerShell:
+Uninstall:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/MichaelCurrin/auto-commit-msg/refs/heads/master/bin/uninstall_cli.sh | bash
+```
+
+### Windows PowerShell
+
+**Warning this is untested**
 
 ```powershell
 iwr https://github.com/username/repo/releases/latest/download/install.ps1 -useb | iex
 ```
 
-> [!TIP]
-> To setup as a **pre-commit hook**, see [Shell](/shell/)
+## Setup as a hook
+
+To setup as a **pre-commit hook**, see [Shell](/shell/)
 
 ## Usage
 

src/autofill.ts

@@ -5,19 +5,16 @@ import * as vscode from "vscode";
 import { Repository } from "./api/git";
 import { getChanges } from "./git/cli";
 import { getCommitMsg, setCommitMsg } from "./gitExtension";
+import { NO_LINES_MSG } from "./lib/constants";
 import { generateMsg } from "./prepareCommitMsg";
 
-export const NO_LINES_MSG = `\
-Unable to generate message as no changes files can be seen.
-Try saving your files or stage any new (untracked) files.\
-`;
-
 /**
  * Generate and fill a commit message in the Git extension sidebar.
  *
  * Steps:
  *
- *   1. Read Git command output and the message in the Git Extension commit message box.
+ *   1. Read Git command output and the message in the Git Extension commit
+ *      message box.
  *   2. Generate a message.
  *   3. Push message value to the commit message box.
  *

src/cli/diffIndexGenerate.ts

@@ -3,89 +3,71 @@
  * AutoCommitMsg CLI script - to check Git changes and generate a commit message.
  */
 import { execFileSync } from "child_process";
+import { Repository } from "../api/git";
+import { getChanges } from "../git/cli";
+import { NO_LINES_MSG } from "../lib/constants";
 import { generateMsg } from "../prepareCommitMsg";
 import { shouldShowHelp } from "./utils";
 
-const HELP_TEXT: string = `Usage: acm [--cached] [--help|-h]
+const HELP_TEXT: string = `Usage: acm [--help|-h]
 
-Check Git changes and generate a commit message.
+Check Git changes and output a generated commit message.
 
 Options:
-  --cached        Use only staged changes (equivalent to \`git --cached\`).
-                  If the flag is omitted, then the standard \`git commit\` logic is followed:
-    look for staged changes and use them, otherwise use unstaged changes.
-  --help, -h      Show this help and exit.`;
+  --help, -h      Show this help and exit.
+  --verbose       Show debug output for this run.
+`;
 
-const DIFF_FLAGS = [
-  "diff-index",
-  "--name-status",
-  "--find-renames",
-  "--find-copies",
-  "--no-color",
-];
-
-/**
- * Run `git diff-index` and return its stdout as a string.
- *
- * TODO: Use _diffIndex instead after refactoring for flags.
- * @param useCached When true, include only staged changes using `--cached`.
- *
- * @returns output Diff output from git.
- */
-function runGitDiff(useCached: boolean): string {
-  const flags: string[] = [...DIFF_FLAGS];
-
-  if (useCached) {
-    flags.push("--cached");
-  }
-  flags.push("HEAD");
-
-  const output: string = execFileSync("git", flags, {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  return output.trim();
+function _getCurrentRepository(): Repository {
+  return {
+    rootUri: {
+      fsPath: execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+      }).trim(),
+    },
+  } as Repository;
 }
 
 /**
  * Generate a commit message from the current repository diff.
  *
- * @param useCached When true, include only staged changes using `--cached`.
  * @returns Generated commit message text.
  */
-export function generateCommitMessage(useCached: boolean): string {
-  const diffOutput: string = runGitDiff(useCached);
-  if (!diffOutput) {
-    throw new Error("No file changes found");
+export async function generateCommitMessage(): Promise<string> {
+  const repo = _getCurrentRepository();
+  const fileChanges: string[] = await getChanges(repo);
+  if (!fileChanges.length) {
+    // todo how to handle elegantly at next level here and other script
+    throw new Error(NO_LINES_MSG);
   }
 
-  const lines: string[] = diffOutput.split("\n");
-  return generateMsg(lines);
+  return generateMsg(fileChanges);
 }
 
 /**
  * Command-line entry-point.
  *
- * Accepts an optional `--cached` flag to use staged changes only.
  * Prints the generated commit message to stdout.
  */
-function main(argv: string[]): void {
+async function main(argv: string[]): Promise<void> {
   if (shouldShowHelp(argv)) {
     console.log(HELP_TEXT);
     return;
   }
-  const useCached: boolean = argv.includes("--cached");
-  const msg: string = generateCommitMessage(useCached);
+
+  const verbose: boolean = argv.includes("--verbose");
+  if (verbose) {
+    process.env.ACM_DEBUG = "1";
+  }
+
+  const msg: string = await generateCommitMessage();
   console.log(msg);
 }
 
 if (require.main === module) {
-  try {
-    main(process.argv.slice(2));
-  } catch (err) {
+  main(process.argv.slice(2)).catch((err: unknown) => {
     const message: string = err instanceof Error ? err.message : String(err);
     console.error(`Error: ${message}`);
     process.exit(1);
-  }
+  });
 }

src/cli/diffIndexGenerateCommit.ts

@@ -6,44 +6,66 @@ import { execFileSync } from "child_process";
 import { generateCommitMessage } from "./diffIndexGenerate";
 import { shouldShowHelp } from "./utils";
 
-const HELP_TEXT: string = `Usage: gacm [--cached] [--help|-h]
+const HELP_TEXT: string = `Usage: gacm [--dry-run] [--no-edit|-n] [--help|-h]
 
 Check Git changes, generate a commit message, and run Git commit.
 
+As with standard git commit behavior, staged files will be used if there are any,
+then it falls back to unstaged files (like \`git commit .\`) and as per standard
+git behavior the untracked files will be ignored.
+
 Options:
-  --cached        Use only staged changes (equivalent to \`git --cached\`).
-                  If the flag is omitted, then the standard \`git commit\` logic is followed:
-    look for staged changes and use them, otherwise use unstaged changes.
-  --help, -h      Show this help and exit.`;
+  --help, -h      Show this help and exit.
+  --dry-run       Do not commit, just print what would be sent to git commit.
+  --no-edit -n    Do not edit the commit message manually - commit directly.
+`;
 
 /**
  * Command-line entry-point.
  */
-function main(argv: string[]): void {
+async function main(argv: string[]): Promise<void> {
   if (shouldShowHelp(argv)) {
     console.log(HELP_TEXT);
     return;
   }
 
-  const useCached: boolean = argv.includes("--cached");
-  const passthrough: string[] = argv.filter(
-    (arg: string) => arg !== "--cached",
-  );
+  const dryRun: boolean = argv.includes("--dry-run");
+  const noEdit: boolean = argv.includes("--no-edit") || argv.includes("-n");
+
+  // Note that this should to be escaped/quoted. Even though it looks weird in
+  // the dry-run output, it works correctly (otherwise quotes appear in the
+  // commit message).
+  const msg = await generateCommitMessage();
+  const commitArgs: string[] = ["commit", "-m", msg];
+  if (!noEdit) {
+    commitArgs.push("--edit");
+  }
 
-  const msg: string = generateCommitMessage(useCached);
+  let command: string;
+  let args: string[];
+
+  if (dryRun) {
+    command = "echo";
+    args = ["git", ...commitArgs];
+  } else {
+    command = "git";
+    args = commitArgs;
+  }
 
-  // FIXME: there is a bug when using changes that are not staged and without
-  // --cached flag, so the message is unquoted.
-  const commitArgs: string[] = ["commit", "--edit", "-m", msg, ...passthrough];
-  execFileSync("git", commitArgs, { stdio: "inherit" });
+  try {
+    execFileSync(command, args, { stdio: "inherit" });
+  } catch (err: unknown) {
+    // Retry current directory for unstaged files. Note passing specific paths
+    // here does not make sense as it wouldn't match the message generation
+    // logic.
+    execFileSync("git", [...commitArgs, "."], { stdio: "inherit" });
+  }
 }
 
 if (require.main === module) {
-  try {
-    main(process.argv.slice(2));
-  } catch (err) {
+  main(process.argv.slice(2)).catch((err: unknown) => {
     const message: string = err instanceof Error ? err.message : String(err);
     console.error(`Error: ${message}`);
     process.exit(1);
-  }
+  });
 }

src/cli/generate.ts

@@ -36,14 +36,14 @@ function main(args: string[]): void {
     console.log(HELP_TEXT);
     return;
   }
-  const linesArg = args[0];
 
-  if (typeof linesArg === "undefined") {
+  if (!args.length) {
     throw new Error(
       "Exactly one argument is required - text output from diff-index command.",
     );
   }
 
+  const linesArg = args[0];
   const lines = linesArg.split("\n");
 
   if (!lines.length) {

src/extension.ts

@@ -60,14 +60,14 @@ async function _handleRepo(git: API): Promise<Repository> {
  * Choose the relevant repo and apply autofill logic on files there.
  */
 async function _chooseRepoForAutofill(sourceControl?: vscode.SourceControl) {
-  const git = getGitExtension()!;
-  _validateFoundRepos(git);
+  const gitExtension = getGitExtension()!;
+  _validateFoundRepos(gitExtension);
 
   vscode.commands.executeCommand("workbench.view.scm");
 
   const selectedRepo = sourceControl
-    ? await _handleRepos(git, sourceControl)
-    : await _handleRepo(git);
+    ? await _handleRepos(gitExtension, sourceControl)
+    : await _handleRepo(gitExtension);
 
   if (!selectedRepo) {
     const msg = "No repos found";

src/git/cli.ts

@@ -21,13 +21,20 @@ const DIFF_INDEX_OPTIONS = [
   "--no-color",
 ];
 
+// Allow debug messages to be shown (VS Code extension) or hidden (CLI tool).
+function debug(...args: unknown[]): void {
+  if (process.env.ACM_DEBUG === "1") {
+    console.debug(...args);
+  }
+}
+
 /**
  * Run a `git` subcommand and return the result, with stdout and stderr available.
  */
 function _execute(cwd: string, subcommand: string, options: string[] = []) {
   const command = `git ${QUOTE_PATH} ${subcommand} ${options.join(" ")}`;
 
-  console.debug(`Running command: ${command}, cwd: ${cwd}`);
+  debug(`Running command: ${command}, cwd: ${cwd}`);
 
   return exec(command, { cwd });
 }
@@ -54,7 +61,7 @@ async function _diffIndex(
   const { stdout, stderr } = await _execute(cwd, DIFF_INDEX_CMD, fullOptions);
 
   if (stderr) {
-    console.debug(`stderr for 'git ${DIFF_INDEX_CMD}' command:`, stderr);
+    debug(`stderr for 'git ${DIFF_INDEX_CMD}' command:`, stderr);
   }
 
   const lines = stdout.split("\n");
@@ -75,19 +82,19 @@ export async function getChanges(repository: Repository) {
   const stagedChanges = await _diffIndex(repository, ["--cached"]);
 
   if (stagedChanges.length) {
-    console.debug("Found staged changes");
+    debug("Found staged changes");
 
     return stagedChanges;
   }
 
-  console.debug(
+  debug(
     "Staging area is empty. Using unstaged files (tracked files only still).",
   );
 
   const allChanges = await _diffIndex(repository);
 
   if (!allChanges.length) {
-    console.debug("No changes found");
+    debug("No changes found");
   }
   return allChanges;
 }