dsh-patch-apply

Usage

1. dsh tools

Tool	Purpose
patch_apply	Apply a unified diff, all-or-nothing, with undo journaling.
patch_dry_run	Validate applicability; report every conflict; write nothing.
patch_reverse	Produce the reverse patch (validated first) without applying.
patch_stat	Summarise a patch (files, hunks, +/−/context counts) without touching the filesystem.

Common arguments:

• patch (string, required) — the unified diff text.
• cwd (string, optional) — base directory for relative paths (default: config.defaultRoot).
• dry_run / verify_sha (boolean, optional) — dry-run mode / hard SHA-1 mismatch.

patch_apply returns:

{
  "ok": true,
  "dryRun": false,
  "files": [{ "path": "...", "operation": "modify", "hunks": [{ "hunkNumber": 1, "status": "offset", "atLine": 12 }] }],
  "conflicts": [],            // [{ file, hunkNumber, sourceLine, reason, expected[], actual[], anchorLine }]
  "errors": [],               // [{ code, path, message }]
  "notes": [],                // informational, e.g. SHA-1 pre-flight mismatches
  "reversePatch": "diff --git ...",
  "undoFile": "/abs/.dsh-patch-undo.json"
}

files lists each prepared file operation with its per-hunk statuses — what was applied on success, or what would be applied in dry-run. All-or-nothing means: ok: false (any non-empty conflicts/errors) guarantees nothing was written, and on success every hunk of every file was located and committed.

2. CLI

dsh-patch  [options] 

Commands
  apply   
    apply a unified diff (writes an undo journal by default)
  dry-run 
    validate applicability; report conflicts; never write
  reverse 
    print the reverse patch (or write it with --out)
  stat    
    summarize a patch without touching the filesystem
  undo      apply the reverse patch recorded in an undo journal
  help               show this help

Options
  --root       base directory for relative patch paths (default: cwd)
  --dry-run         alias for dry-run behavior on 'apply'
  --no-undo         do not write an undo journal
  --undo-file 
   undo journal path for 'apply' (default: /.dsh-patch-undo.json)
  --fuzz         max leading context lines droppable in fuzzy match (default: 3)
  --strict-sha      treat index-line SHA-1 mismatches as hard conflicts
  --out       write reverse output to a file instead of stdout
  --json            machine-readable JSON output on stdout
  --help            show this help

Exit codes: 0 success · 1 the patch could not be applied · 2 usage error.

dsh-patch apply changes.patch --root /workspace
dsh-patch dry-run changes.patch
dsh-patch reverse changes.patch > revert.patch
dsh-patch undo .dsh-patch-undo.json

3. Library

import { applyPatchText } from 'dsh-patch-apply'

const report = await applyPatchText(patchText, {
  root: process.cwd(),          // absolute base for relative paths
  fuzzContext: 3,               // fuzzy tolerance
  dryRun: false,                // validate only?
  undo: true,                   // write an undo journal?
  undoFile: '.dsh-patch-undo.json',
  strictSha: false,             // index SHA-1 mismatches as hard conflicts?
})

Other exports: parsePatch, statPatch, applyUndo(journal), readJournal / writeJournal, blobSha, the IoAdapter/NodeIoAdapter/ CtxFsIoAdapter filesystem seam, and the typed error classes.

---