@procedures/git 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @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
+
+- 4cad9ab: More git procedures (roadmap R40): `git.show`, `git.blame`, `git.tag.list`, `git.tag.add`, `git.tag.delete`, `git.revParse`, `git.reset`, `git.restore`, `git.merge`, `git.merge.abort`, `git.rebase`, `git.rebase.continue`, `git.rebase.abort`, `git.worktree.list`, `git.worktree.add` and `git.worktree.remove`. Each one declares its effects. A merge or a rebase that stops on conflicts gives `conflict: true` and the files, and git never starts an editor.
+  
+  `git.branch` becomes three procedures: `git.branch.list`, `git.branch.add` and `git.branch.delete`. `git.branch` is deprecated. It stays for one release with the same input and output, and it calls the new code.
+  
+  The current branch comes from `git symbolic-ref`. Before, `git.branch` and `git.push` used `git rev-parse --abbrev-ref HEAD`, which fails in a repository without commits. `git.branch.list` and `git.branch` work there now.
+
+### Patch Changes
+
+- 95b660d: Three defects that the new tests of roadmap R33 found:
+  
+  - `git.commit` gives `skipped: true` when nothing is staged. Before, an untracked file or a change that was not staged made `git commit` fail with "nothing added to commit". With `all`, a change of a tracked file is a change to commit, and an untracked file is not.
+  - `git.init` looks for `.git` itself. Before, it used `fs.exists` through its context, so it failed in a registry of `gitModule` alone (`createRegistry(gitModule)`).
+  - A component of `@procedures/splay` gives its registry to the children that it renders. Before, the child of a child came from the global registry, so a component in a registry of `createRegistry()` rendered an "unknown" grandchild.
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+  - @procedures/shell@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -3,13 +3,13 @@
 [![npm version](https://img.shields.io/npm/v/@procedures/git.svg)](https://www.npmjs.com/package/@procedures/git)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Git operations as RPC procedures - `git.add`, `git.commit`, `git.push`, `git.status`, and 22 more git commands exposed as type-safe procedures.
+> Git operations as RPC procedures - `git.add`, `git.commit`, `git.push`, `git.status`, and 41 more git commands exposed as type-safe procedures.
 
 ## Overview
 
-`@procedures/git` exposes comprehensive Git functionality as RPC procedures through the client system. It provides 26 procedures covering all major Git operations including repository state management, staging, commits, branching, remote operations, stashing, and repository predicates.
+`@procedures/git` exposes comprehensive Git functionality as RPC procedures through the client system. It provides 45 procedures covering all major Git operations including repository state management, staging, commits, branching, tags, merges, rebases, working trees, remote operations, stashing, and repository predicates.
 
-This package wraps Git commands directly (not through `client-shell`), providing structured input/output with full type safety via Zod schemas.
+The package starts git with `runCommand` of `@procedures/shell`: an argument list, no shell. Each call is async, and its signal stops git. Zod schemas validate the input and the output.
 
 ## Architecture
 
@@ -36,11 +36,12 @@ graph TB
 
 ```mermaid
 graph LR
-    A[client-git<br/>26 Procedures] --> B[Repository State<br/>5 procedures]
+    A[client-git<br/>45 Procedures] --> B[Repository State<br/>5 procedures]
     A --> C[Staging & Commits<br/>3 procedures]
     A --> D[Remote Operations<br/>5 procedures]
     A --> E[Predicates<br/>6 procedures]
     A --> F[Stash Operations<br/>7 procedures]
+    A --> G[History, Tags, Merge, Rebase,<br/>Working Trees, Branches<br/>19 procedures]
 
     B -.-> B1[status, log, diff,<br/>branch, init]
     C -.-> C1[add, commit,<br/>checkout]
@@ -107,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 {
@@ -135,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.
@@ -226,10 +238,12 @@ console.log(`${diff.additions} additions, ${diff.deletions} deletions`);
 const staged = await client.exec(["git", "diff"], { staged: true });
 ```
 
-#### `git.branch`
+#### `git.branch` (deprecated)
 
 Branch operations - list, create, delete branches.
 
+This procedure is deprecated since roadmap R40. Use `git.branch.list`, `git.branch.add` and `git.branch.delete`. It stays for one release, and it calls the code of the three new procedures. Its metadata has `deprecated: true`.
+
 **Path:** `["git", "branch"]`
 
 ```typescript
@@ -344,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;
 }
@@ -367,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.
@@ -841,6 +868,51 @@ const exported = await client.exec(["git", "stash", "export"], { index: 0 });
 fs.writeFileSync("backup.patch", exported.patch);
 ```
 
+### History, tags, merges, rebases and working trees (roadmap R40)
+
+Each procedure takes `cwd`, the folder of the repository. A value that starts with `-` is not an option: a ref or a name is refused, and a path stays a path after `--`. The effects column shows `metadata.effects`. "process" means that git starts the hooks of the repository, which are code of the project.
+
+| Procedure | Input | Output | Effects |
+|---|---|---|---|
+| `git.show` | `ref` (default `HEAD`), `path`, `stat` | Without `path`: `hash`, `author`, `email`, `date`, `message`, `body`, `files`, `diff`. With `path`: `content` | reads |
+| `git.blame` | `path`, `ref`, `startLine`, `endLine` | `lines`: `line`, `hash`, `author`, `email`, `date`, `summary`, `content` | reads |
+| `git.tag.list` | `pattern` | `tags`: `name`, `hash` (the commit), `annotated`, `message` | reads |
+| `git.tag.add` | `name`, `ref`, `message` | `name`, `hash`, `annotated` | writes, not destructive, idempotent |
+| `git.tag.delete` | `name` | `name`, `hash` (the object of the tag) | writes, destructive, idempotent |
+| `git.revParse` | `ref` (default `HEAD`), `abbrevRef`, `short` | `ref`, `value` | reads |
+| `git.reset` | `ref` (default `HEAD`), `mode` (`soft`, `mixed`, `hard`, `merge`, `keep`), `paths` | `ref`, `mode`, `hash` | writes, destructive |
+| `git.restore` | `paths`, `source`, `staged`, `worktree` | `restored` | writes, process, destructive, idempotent |
+| `git.merge` | `ref`, `fastForward` (`auto`, `only`, `never`), `message` | `hash`, `fastForward`, `upToDate`, `conflict`, `conflicts` | writes, process, idempotent |
+| `git.merge.abort` | none | `aborted`, `hash` | writes, destructive, idempotent |
+| `git.rebase` | `upstream`, `onto`, `branch` | `hash`, `completed`, `upToDate`, `conflict`, `conflicts` | writes, process, destructive, idempotent |
+| `git.rebase.continue` | none | the output of `git.rebase` | writes, process, destructive |
+| `git.rebase.abort` | none | `aborted`, `hash` | writes, destructive, idempotent |
+| `git.worktree.list` | none | `worktrees`: `path`, `head`, `branch`, `detached`, `bare`, `locked`, `prunable` | reads |
+| `git.worktree.add` | `path`, `ref`, `branch`, `detach` | `path`, `head`, `branch` | writes, process, not destructive, idempotent |
+| `git.worktree.remove` | `path`, `force` | `path` | writes, destructive, idempotent |
+| `git.branch.list` | `remote` | `branches`, `current` | reads |
+| `git.branch.add` | `name`, `startPoint` | `name`, `hash` | writes, not destructive, idempotent |
+| `git.branch.delete` | `name`, `force` | `name`, `hash` (the last commit) | writes, destructive, idempotent |
+
+- A merge or a rebase that stops on conflicts is a result, not an error. Then `conflict` is `true`, and `conflicts` names the files.
+- After the conflicts of a merge, resolve them and call `git.commit`, or call `git.merge.abort`.
+- After the conflicts of a rebase, resolve them, stage them with `git.add`, and call `git.rebase.continue`. Or call `git.rebase.abort`.
+- A merge and a rebase never start an editor. The rebase is never interactive.
+- `git.tag.add` and `git.branch.add` never move a ref. An existing tag or branch is an error.
+- `git.branch.delete` and `git.tag.delete` give the deleted hash. `git.branch.add` with it makes the branch again.
+- `git.branch.list` works in a repository without commits. Then `branches` is empty and `current` is the branch that `HEAD` names.
+
+```typescript
+const merge = await client.exec(["git", "merge"], { ref: "feature", cwd: "./repo" });
+if (merge.conflict) {
+  console.log("Conflicts in", merge.conflicts);
+  await client.exec(["git", "merge", "abort"], { cwd: "./repo" });
+}
+
+const { lines } = await client.exec(["git", "blame"], { path: "src/index.ts", startLine: 1, endLine: 10 });
+const { value: branch } = await client.exec(["git", "revParse"], { abbrevRef: true });
+```
+
 ## Complete Procedure List
 
 | Category | Procedure | Description |
@@ -848,8 +920,27 @@ fs.writeFileSync("backup.patch", exported.patch);
 | **Repository State** | `git.status` | Get repository status |
 | | `git.log` | Show commit history |
 | | `git.diff` | Show changes |
-| | `git.branch` | Branch operations |
+| | `git.show` | Show a commit, or a file at a commit |
+| | `git.blame` | Show the commit and the author of each line |
+| | `git.revParse` | Give the hash or the name of a ref |
+| | `git.branch` | Branch operations (deprecated) |
 | | `git.init` | Initialize repository |
+| **Branches and Tags** | `git.branch.list` | List the branches |
+| | `git.branch.add` | Make a branch |
+| | `git.branch.delete` | Delete a branch |
+| | `git.tag.list` | List the tags |
+| | `git.tag.add` | Make a tag |
+| | `git.tag.delete` | Delete a tag |
+| **Merge and Rebase** | `git.merge` | Merge into the current branch |
+| | `git.merge.abort` | Stop a merge with conflicts |
+| | `git.rebase` | Rebase the current branch |
+| | `git.rebase.continue` | Continue a rebase |
+| | `git.rebase.abort` | Stop a rebase |
+| **Working Trees** | `git.worktree.list` | List the working trees |
+| | `git.worktree.add` | Add a working tree |
+| | `git.worktree.remove` | Remove a working tree |
+| **Undo** | `git.reset` | Move `HEAD`, reset the index or the working tree |
+| | `git.restore` | Restore files |
 | **Staging & Commits** | `git.add` | Stage files |
 | | `git.commit` | Create commit |
 | | `git.checkout` | Checkout branch/files |
@@ -932,11 +1023,9 @@ await client.exec(["git", "commit"], { message: "feat: complete feature" });
 await client.exec(["git", "checkout"], { ref: "main" });
 await client.exec(["git", "pull"], {});
 
-// Delete feature branch
-await client.exec(["git", "branch"], {
-  name: "feature/new-feature",
-  delete: true,
-});
+// Merge it, then delete the feature branch
+await client.exec(["git", "merge"], { ref: "feature/new-feature" });
+await client.exec(["git", "branch", "delete"], { name: "feature/new-feature" });
 ```
 
 ### Working with Remotes
@@ -949,7 +1038,7 @@ const clone = await client.exec(["git", "clone"], {
 });
 
 // Set remote
-await client.exec(["git", "remote"], {
+await client.exec(["git", "remote", "set"], {
   name: "upstream",
   url: "https://github.com/original/repo.git",
 });
@@ -1013,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:
+
+```typescript
+import "@procedures/git/register";
+```
 
-Procedures are automatically registered when the package is loaded:
+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"
   }
 }
 ```
@@ -1055,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