@procedures/git 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @procedures/git
 
+## 0.4.0
+
+### Minor Changes
+
+- 0ecc788: `git.status` and `git.commit` take `paths`, and the package root exports the git runner and a parser of `git status --porcelain=v1 -z`.
+  
+  - `git.status` has two new options: `paths` (the pathspecs after `--`) and `untrackedFiles` (`--untracked-files=no|normal|all`). With `"all"`, git gives each file of a new folder. Without the options, the output does not change.
+  - `git.commit` has the new option `paths`. The commit then has only those paths, as they are in the working tree (`git commit -m <message> -- <paths>`). The other staged changes stay in the index.
+  - With `paths`, a change of a tracked file counts, staged or not. When no tracked file of the paths changed, the output has `skipped: true`. `all` and `paths` together give an error, because git refuses `-a` with paths.
+  - `parsePorcelainV1(output)` gives each entry with `xy`, the exact `path`, `status` and `staged`, and `from` for a rename or a copy. `classifyStatus(xy)` gives the status of two status letters.
+  - The root also exports `git(args, options)`, the runner of the procedures. It throws a `GitError` when git fails.
+  
+  The effects of `git.status` and `git.commit` do not change.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4c51727]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/shell@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -108,6 +108,10 @@ interface GitStatusInput {
   cwd?: string;
   /** Also give `lines` in the format of `git status --short` (default: false) */
   short?: boolean;
+  /** Only the files of these pathspecs (`git status -- <paths>`) */
+  paths?: string[];
+  /** `--untracked-files`: "no", "normal" (a new folder is one entry) or "all" (each file) */
+  untrackedFiles?: "no" | "normal" | "all";
 }
 
 interface GitStatusFile {
@@ -136,8 +140,15 @@ const status = await client.exec(["git", "status"], { cwd: "./my-repo" });
 console.log(`On branch ${status.branch}`);
 console.log(`${status.ahead} commits ahead, ${status.behind} behind`);
 console.log(`${status.files.length} changed files`);
+
+// Each new file under notes/, one entry for each file
+const notes = await client.exec(["git", "status"], { cwd: "./my-repo", paths: ["notes"], untrackedFiles: "all" });
 ```
 
+- Without `paths` and `untrackedFiles`, the procedure starts the same git command as before.
+- After `--`, git reads each path as a pathspec. A path that starts with `-` is not an option.
+- Without `untrackedFiles: "all"`, git gives a new folder as one entry, for example `notes/`.
+
 #### `git.log`
 
 Show commit history.
@@ -347,6 +358,8 @@ interface GitCommitInput {
   all?: boolean;
   /** Amend the last commit (default: false) */
   amend?: boolean;
+  /** Commit only these pathspecs, as they are in the working tree (`git commit -- <paths>`) */
+  paths?: string[];
   /** Working directory */
   cwd?: string;
 }
@@ -370,6 +383,17 @@ const commit = await client.exec(["git", "commit"], {
 console.log(`Created commit ${commit.hash}`);
 ```
 
+With `paths`, the commit has only those paths, as they are in the working tree. The other staged changes stay in the index:
+
+```typescript
+await client.exec(["git", "add"], { paths: ["ledger/new.ndjson"] });
+await client.exec(["git", "commit"], { message: "ledger: the day", paths: ["ledger"] });
+```
+
+- With `paths`, a change of a tracked file counts, staged or not. When no tracked file of the paths changed, the output has `skipped: true`.
+- git does not commit an untracked file. Add a new file with `git.add` first.
+- git refuses `-a` with paths. Thus `all` and `paths` together give an error.
+
 #### `git.checkout`
 
 Checkout branch, tag, or restore files.
@@ -1078,17 +1102,20 @@ export async function commit(
 
 ## Configuration
 
-### Auto-Registration
+### Registration
+
+An import of the package root registers nothing. Import the `./register` entry to register the procedures in the global registry:
 
-Procedures are automatically registered when the package is loaded:
+```typescript
+import "@procedures/git/register";
+```
+
+The `client.procedures` field of `package.json` names that entry. `mark` finds the package by this field:
 
 ```json
 {
   "client": {
     "procedures": "./dist/register.js"
-  },
-  "scripts": {
-    "postinstall": "client-registry announce"
   }
 }
 ```
@@ -1120,6 +1147,22 @@ await gitCommit({ message: "feat: new feature", cwd: "./repo" });
 await gitPush({ remote: "origin", cwd: "./repo" }, { signal: AbortSignal.timeout(60_000) });
 ```
 
+### The git runner and the porcelain parser
+
+The package root also exports the functions that the procedures use:
+
+- `git(args, { cwd, signal, input, env })` starts git with an argument list and gives its stdout. It throws a `GitError` when git fails.
+- `parsePorcelainV1(output)` reads the output of `git status --porcelain=v1 -z`.
+- Each entry has `xy` (the two status letters), the exact `path`, `status` and `staged`. A rename or a copy also has `from`.
+- `classifyStatus(xy)` gives the `status` and `staged` of two status letters.
+
+```typescript
+import { git, parsePorcelainV1 } from "@procedures/git";
+
+const output = await git(["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", "ledger"], { cwd: "./repo" });
+const untracked = parsePorcelainV1(output).filter((entry) => entry.status === "untracked");
+```
+
 ### Custom Registration
 
 ```typescript