docs: update 2 files and create 2 files

Author: MichaelCurrin

docs/README.md

@@ -8,23 +8,11 @@ This project serves to prepare a smart commit message for you, to make your deve
 - [Quickstart](quickstart.md)
 - [About](about.md)
 - [Features](features.md)
-    - What it can do, upcoming features, and how it works
+    - What it can do, upcoming features, and how it works,
 - [User manual](manual/)
-    - How to install and use the installed extension.
+    - How to install and use the extension.
+- [CLI](cli.md)
+    - How install and run as a CLI tool only.
 - [Development](development/)
     - Guide for developers to set up and run locally.
     - Useful for testing your changes before contributing a PR.
-
-<!--
-
-The docs are split into two features:
-
-- [Extension](extension.md)
-- [Terminal hook](terminal-hook.md)
-
-Part ideas:
-
-- A shell script in a repo
-- References a concatenated JS script from this repo (just the text handling and not the full extension), which is in a bin directory.
-
--->

docs/cli.md

@@ -0,0 +1,100 @@
+# CLI
+> How to use AutoCommitMsg in the terminal instead of as an extension
+
+See steps below to setup and run the tool in the CLI. VS Code is not needed.
+
+For development, see [CLI Development](development/cli.md).
+
+## Requirements
+
+- Node (see version in [package.json](/package.json))
+- Git
+
+_This should work on Windows too but has not been tested yet._
+
+## Setup
+
+### Clone the repo
+
+```sh
+$ git clone git@github.com:MichaelCurrin/auto-commit-msg.git
+$ cd auto-commit-msg
+```
+
+### Install dependencies
+
+```sh
+$ npm ci
+```
+
+### Build and link the CLI tools
+
+```sh
+$ npm run cli
+```
+
+Verify installation:
+
+```sh
+$ acm -h
+$ gacm -h
+```
+
+## Usage
+
+Use the `-h` or `--help` flags with any of these to avoid making changes.
+
+<!--
+TODO consolidate to one command with commit flag or dry run?
+TODO pass params like file names through for either command. For message and committing. The downside is for new files - even if git commit would pick them up by name, diff-index would not. You can also use whatever IDE to stage and still generate+commit with the CLI.
+TODO -c not just --cached but pass through as --cached.
+    And use default behavior for if there is staged then use that for commit message - make it smart.
+-->
+
+### Generate a message from changes and commit
+
+This is the **main** command you should use.
+
+Note this actually **commit**, so if you want to experiment with commit output **without** committing, use the command below instead.
+
+No flags are needed.
+
+```sh
+$ gacm
+```
+
+### Check Git changes and generate commit message
+
+This will **not** commit.
+
+No flags are needed.
+
+```sh
+$ acm
+```
+
+### Generate a message from staged changes
+
+This is a simpler command which does not interact with Git, intended for integrating with the Bash shell.
+
+See [shell/acm.sh](/shell/acm.sh) if you want to use that script or write your own shell script. That relies on using this executable Node script
+
+```sh
+$ auto_commit_message_generate "$CHANGES"
+```
+
+### Usage tips
+
+The behavior depends on how Git treats files, so you should know these points:
+
+- The commands will pick up on staged changes and certain unstaged changes (modified and deleted, but not created as they are untracked).
+- If you want to handle created files, make sure to stage them first.
+- If you want to target only select changes for smaller commit, then stage stages and use the `--cached` flag to ignored unstaged changes.
+
+## Uninstall the linked CLI (optional)
+
+If you get permission denied error, you can do this and then go back to the install step.
+
+```sh
+$ npm unlink -g auto-commit-msg
+```

docs/development/cli.md

@@ -0,0 +1,43 @@
+# CLI Development
+> Maintaining code around the CLI tool
+
+The code is in [src/cli/](/src/cli). The CLI commands are built using steps set in [package.json](/package.json) - see the `cli` command and `bin` section.
+
+
+
+## Run directly
+
+```sh
+$ npx ts-node src/cli/diffIndexGenerate.ts
+```
+
+
+## Package as a binary
+
+To send to someone so they can use it without having Node installed or running a build step on their machine.
+
+```sh
+$ npx --yes pkg out/cli/diffIndexGenerateCommit.js -t node18-macos
+```
+
+## Troubleshooting
+
+On macOS, installed here as a symlink pointing to the `.js` file in the repo:
+
+```
+/opt/homebrew/bin/acm
+```
+
+If you get permissions issues, it is because the `.js` file was rebuilt and with standard permissions and needs to be linked again.
+
+```sh
+$ npm run cli
+```
+
+Check:
+
+```sh
+ls -l $(realpath /opt/homebrew/bin/acm)
+```
+
+See [package.json](/package.json). Supposedly you should be able to leave out the project name when running `npm link` via an `npm run ...` command but I found this causes issues, so decided to always use the full name in the configuration. And to _always_ unlink then link in one go because of permissions issues.

docs/features.md

@@ -16,14 +16,7 @@ A roadmap of features and whether done or not.
     - Note that **new** files (including when doing a rename) should **always** be staged so that the extension can pick them up and so git can see that two paths for a renamed file are the same file.
 - [x] Generate a single-line commit message for a file to be committed, using action verbs (e.g. `Create`, `Update`, `Delete`)
 - [x] Handle changes from a single changed file.
-- [ ] Handle changes from two or more files.
-    - [x] As a list of the same nature e.g. `update foo.txt and fizz/bar.txt`, `feat: create foo.txt, fizz/bar.txt and buzz.js` (including prefix) and `Various changes to foo.txt and fizz/bar.txt` (for one updated and one new file). See [#29](https://github.com/MichaelCurrin/auto-commit-msg/pull/29).
-    - [x] As a count. e.g. `update 3 files`. See [#38](https://github.com/MichaelCurrin/auto-commit-msg/issues/38).
-    - [ ] As different verb for each change `create foo.txt and delete bar.txt`. See [#37](https://github.com/MichaelCurrin/auto-commit-msg/issues/37) and See [#52](https://github.com/MichaelCurrin/auto-commit-msg/issues/52).
-    - [ ] As a count in a directory. `update 3 files in foo`
-    - [ ] As a count with a conventional commit message. See [#51](https://github.com/MichaelCurrin/auto-commit-msg/issues/51).
-    - [ ] As a count with a label. e.g. `update 3 config files`. See [#13](https://github.com/MichaelCurrin/auto-commit-msg/issues/13).
-    - [ ] As count that uses the old message. See [#55](https://github.com/MichaelCurrin/auto-commit-msg/issues/55)
+- [x] Handle changes from two or more files.
 - [x] Support using multiple repos in one VS Code window.
 - [x] Keep user-entered value as a prefix e.g. Keep `docs:` (or ticket number) so message becomes `docs: Update README.md`
 - [x] Use conventional commits e.g. `chore: Update package.json`