workspace-tools 0.38.5 → 0.40.0

package/lib/{workspaces/readPackageInfo.d.ts → getPackageInfo.d.ts}

@@ -1,13 +1,13 @@
-import type { PackageInfo } from "../types/PackageInfo";
+import type { PackageInfo } from "./types/PackageInfo";
 /**
  * Read package.json from the given path if it exists.
  * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
  * @returns The package info, or undefined if it doesn't exist or can't be read
  */
-export declare function readPackageInfo(cwd: string): PackageInfo | undefined;
+export declare function getPackageInfo(cwd: string): PackageInfo | undefined;
 /**
  * Read package.json from the given path if it exists.
  * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
  * @returns The package info, or undefined if it doesn't exist or can't be read
  */
-export declare function readPackageInfoAsync(cwd: string): Promise<PackageInfo | undefined>;
+export declare function getPackageInfoAsync(cwd: string): Promise<PackageInfo | undefined>;

package/lib/{workspaces/readPackageInfo.js → getPackageInfo.js}

@@ -3,18 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readPackageInfoAsync = exports.readPackageInfo = void 0;
+exports.getPackageInfoAsync = exports.getPackageInfo = void 0;
 const fs_1 = __importDefault(require("fs"));
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const infoFromPackageJson_1 = require("../infoFromPackageJson");
-const logging_1 = require("../logging");
+const infoFromPackageJson_1 = require("./infoFromPackageJson");
+const logging_1 = require("./logging");
 /**
  * Read package.json from the given path if it exists.
  * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
  * @returns The package info, or undefined if it doesn't exist or can't be read
  */
-function readPackageInfo(cwd) {
+function getPackageInfo(cwd) {
     const packageJsonPath = path_1.default.join(cwd, "package.json");
     try {
         if (!fs_1.default.existsSync(packageJsonPath)) {
@@ -28,13 +28,13 @@ function readPackageInfo(cwd) {
         (0, logging_1.logVerboseWarning)(`Error reading or parsing ${packageJsonPath}: ${e?.message || e}`);
     }
 }
-exports.readPackageInfo = readPackageInfo;
+exports.getPackageInfo = getPackageInfo;
 /**
  * Read package.json from the given path if it exists.
  * Logs a warning if it doesn't exist, or there's an error reading or parsing it.
  * @returns The package info, or undefined if it doesn't exist or can't be read
  */
-async function readPackageInfoAsync(cwd) {
+async function getPackageInfoAsync(cwd) {
     const packageJsonPath = path_1.default.join(cwd, "package.json");
     try {
         if (!fs_1.default.existsSync(packageJsonPath)) {
@@ -48,5 +48,5 @@ async function readPackageInfoAsync(cwd) {
         (0, logging_1.logVerboseWarning)(`Error reading or parsing ${packageJsonPath}: ${e?.message || e}`);
     }
 }
-exports.readPackageInfoAsync = readPackageInfoAsync;
-//# sourceMappingURL=readPackageInfo.js.map
+exports.getPackageInfoAsync = getPackageInfoAsync;
+//# sourceMappingURL=getPackageInfo.js.map

package/lib/getPackageInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPackageInfo.js","sourceRoot":"","sources":["../src/getPackageInfo.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AACpB,2DAAqC;AACrC,gDAAwB;AAExB,+DAA4D;AAC5D,uCAA8C;AAE9C;;;;GAIG;AACH,SAAgB,cAAc,CAAC,GAAW;IACxC,MAAM,eAAe,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI;QACF,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;YACnC,IAAA,2BAAiB,EAAC,wBAAwB,eAAe,EAAE,CAAC,CAAC;YAC7D,OAAO,SAAS,CAAC;SAClB;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAA,yCAAmB,EAAC,WAAW,EAAE,eAAe,CAAC,CAAC;KAC1D;IAAC,OAAO,CAAC,EAAE;QACV,IAAA,2BAAiB,EAAC,4BAA4B,eAAe,KAAM,CAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;KACjG;AACH,CAAC;AAbD,wCAaC;AAED;;;;GAIG;AACI,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,MAAM,eAAe,GAAG,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACvD,IAAI;QACF,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE;YACnC,IAAA,2BAAiB,EAAC,wBAAwB,eAAe,EAAE,CAAC,CAAC;YAC7D,OAAO,SAAS,CAAC;SAClB;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,kBAAU,CAAC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QACpF,OAAO,IAAA,yCAAmB,EAAC,WAAW,EAAE,eAAe,CAAC,CAAC;KAC1D;IAAC,OAAO,CAAC,EAAE;QACV,IAAA,2BAAiB,EAAC,4BAA4B,eAAe,KAAM,CAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;KACjG;AACH,CAAC;AAbD,kDAaC"}

package/lib/getPackageInfos.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPackageInfosAsync = exports.getPackageInfos = void 0;
 const getWorkspaces_1 = require("./workspaces/getWorkspaces");
-const readPackageInfo_1 = require("./workspaces/readPackageInfo");
+const getPackageInfo_1 = require("./getPackageInfo");
 /**
  * Read all the package.json files in a monorepo. Only works for monorepos which
  * use a supported workspace manager.
@@ -17,7 +17,7 @@ function getPackageInfos(cwd) {
         }
     }
     else {
-        const rootInfo = (0, readPackageInfo_1.readPackageInfo)(cwd);
+        const rootInfo = (0, getPackageInfo_1.getPackageInfo)(cwd);
         if (rootInfo) {
             packageInfos[rootInfo.name] = rootInfo;
         }
@@ -43,7 +43,7 @@ async function getPackageInfosAsync(cwd) {
         }
     }
     else {
-        const rootInfo = (0, readPackageInfo_1.readPackageInfo)(cwd);
+        const rootInfo = (0, getPackageInfo_1.getPackageInfo)(cwd);
         if (rootInfo) {
             packageInfos[rootInfo.name] = rootInfo;
         }

package/lib/getPackageInfos.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPackageInfos.js","sourceRoot":"","sources":["../src/getPackageInfos.ts"],"names":[],"mappings":";;;AACA,8DAA+E;AAC/E,kEAA+D;AAE/D;;;;GAIG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,IAAA,6BAAa,EAAC,GAAG,CAAC,CAAC;IAE7C,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,iCAAe,EAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,0CAgBC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,oBAAoB,CAAC,GAAW;IACpD,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,MAAM,IAAA,kCAAkB,EAAC,GAAG,CAAC,CAAC;IAExD,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,iCAAe,EAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,oDAgBC"}
+{"version":3,"file":"getPackageInfos.js","sourceRoot":"","sources":["../src/getPackageInfos.ts"],"names":[],"mappings":";;;AACA,8DAA+E;AAC/E,qDAAkD;AAElD;;;;GAIG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,IAAA,6BAAa,EAAC,GAAG,CAAC,CAAC;IAE7C,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,+BAAc,EAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,0CAgBC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,oBAAoB,CAAC,GAAW;IACpD,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,MAAM,iBAAiB,GAAG,MAAM,IAAA,kCAAkB,EAAC,GAAG,CAAC,CAAC;IAExD,IAAI,iBAAiB,CAAC,MAAM,EAAE;QAC5B,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE;YACnC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAC1C;KACF;SAAM;QACL,MAAM,QAAQ,GAAG,IAAA,+BAAc,EAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,EAAE;YACZ,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;SACxC;KACF;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAhBD,oDAgBC"}

package/lib/git/config.d.ts

@@ -0,0 +1,8 @@
+import { GitCommonOptions } from "./types";
+/**
+ * Get the value of a git config key. Returns null if it's not set.
+ * (Note: setting `throwOnError: true` will cause it to fail if the key is unset.)
+ */
+export declare function getConfigValue(options: {
+    key: string;
+} & GitCommonOptions): string | null;

package/lib/git/config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigValue = void 0;
+const git_1 = require("./git");
+/**
+ * Get the value of a git config key. Returns null if it's not set.
+ * (Note: setting `throwOnError: true` will cause it to fail if the key is unset.)
+ */
+function getConfigValue(options) {
+    const { key, ...gitOptions } = options;
+    const results = (0, git_1.git)(["config", key], gitOptions);
+    // command failure here just means it's not set
+    return results.success ? results.stdout.trim() : null;
+}
+exports.getConfigValue = getConfigValue;
+// Other config helpers can move here in the future
+//# sourceMappingURL=config.js.map

package/lib/git/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/git/config.ts"],"names":[],"mappings":";;;AAAA,+BAA4B;AAG5B;;;GAGG;AACH,SAAgB,cAAc,CAAC,OAA2C;IACxE,MAAM,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IACvC,MAAM,OAAO,GAAG,IAAA,SAAG,EAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;IACjD,+CAA+C;IAC/C,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AALD,wCAKC;AAED,mDAAmD"}

package/lib/git/getDefaultRemoteBranch.js

@@ -30,7 +30,8 @@ function getDefaultRemoteBranch(...args) {
             .find((line) => line.includes("HEAD branch"))
             ?.replace(/^\s*HEAD branch:\s+/, "");
     }
-    return `${defaultRemote}/${remoteDefaultBranch || (0, gitUtilities_1.getDefaultBranch)(cwd)}`;
+    remoteDefaultBranch || (remoteDefaultBranch = (0, gitUtilities_1.getDefaultBranch)({ cwd, throwOnError: options.strict }));
+    return `${defaultRemote}/${remoteDefaultBranch}`;
 }
 exports.getDefaultRemoteBranch = getDefaultRemoteBranch;
 //# sourceMappingURL=getDefaultRemoteBranch.js.map

package/lib/git/getDefaultRemoteBranch.js.map

@@ -1 +1 @@
-{"version":3,"file":"getDefaultRemoteBranch.js","sourceRoot":"","sources":["../../src/git/getDefaultRemoteBranch.ts"],"names":[],"mappings":";;;AAAA,yDAA+E;AAC/E,+BAA4B;AAC5B,iDAAkD;AAoBlD,SAAgB,sBAAsB,CAAC,GAAG,IAAgD;IACxF,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,MAAM,OAAO,GACX,OAAO,eAAe,KAAK,QAAQ;QACjC,CAAC,CAAE,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,EAAoC;QAC9E,CAAC,CAAC,eAAe,CAAC;IACtB,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEhC,MAAM,aAAa,GAAG,IAAA,mCAAgB,EAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,MAAM,EAAE;QACV,OAAO,GAAG,aAAa,IAAI,MAAM,EAAE,CAAC;KACrC;IAED,MAAM,UAAU,GAAG,IAAA,SAAG,EAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACnE,IAAI,mBAAuC,CAAC;IAE5C,IAAI,UAAU,CAAC,OAAO,EAAE;QACtB;;;;;;;WAOG;QACH,mBAAmB,GAAG,UAAU,CAAC,MAAM;aACpC,KAAK,CAAC,IAAI,CAAC;aACX,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YAC7C,EAAE,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;KACxC;IAED,OAAO,GAAG,aAAa,IAAI,mBAAmB,IAAI,IAAA,+BAAgB,EAAC,GAAG,CAAC,EAAE,CAAC;AAC5E,CAAC;AAjCD,wDAiCC"}
+{"version":3,"file":"getDefaultRemoteBranch.js","sourceRoot":"","sources":["../../src/git/getDefaultRemoteBranch.ts"],"names":[],"mappings":";;;AAAA,yDAA+E;AAC/E,+BAA4B;AAC5B,iDAAkD;AAoBlD,SAAgB,sBAAsB,CAAC,GAAG,IAAgD;IACxF,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,MAAM,OAAO,GACX,OAAO,eAAe,KAAK,QAAQ;QACjC,CAAC,CAAE,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,EAAoC;QAC9E,CAAC,CAAC,eAAe,CAAC;IACtB,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEhC,MAAM,aAAa,GAAG,IAAA,mCAAgB,EAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,MAAM,EAAE;QACV,OAAO,GAAG,aAAa,IAAI,MAAM,EAAE,CAAC;KACrC;IAED,MAAM,UAAU,GAAG,IAAA,SAAG,EAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACnE,IAAI,mBAAuC,CAAC;IAE5C,IAAI,UAAU,CAAC,OAAO,EAAE;QACtB;;;;;;;WAOG;QACH,mBAAmB,GAAG,UAAU,CAAC,MAAM;aACpC,KAAK,CAAC,IAAI,CAAC;aACX,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YAC7C,EAAE,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;KACxC;IAED,mBAAmB,KAAnB,mBAAmB,GAAK,IAAA,+BAAgB,EAAC,EAAE,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,EAAC;IAEhF,OAAO,GAAG,aAAa,IAAI,mBAAmB,EAAE,CAAC;AACnD,CAAC;AAnCD,wDAmCC"}

package/lib/git/git.d.ts

@@ -1,11 +1,17 @@
 /// <reference types="node" />
 /// <reference types="node" />
 /// <reference types="node" />
-import { SpawnSyncReturns } from "child_process";
-import { SpawnSyncOptions } from "child_process";
+import { SpawnSyncOptions, SpawnSyncReturns } from "child_process";
+import { GitCommonOptions } from "./types";
+export type GitOptions = Omit<SpawnSyncOptions, "cwd"> & GitCommonOptions & {
+    /** Operation description to be used in error message (formatted as start of sentence) */
+    description?: string;
+    debug?: boolean;
+};
 export declare class GitError extends Error {
-    originalError: unknown;
-    constructor(message: string, originalError?: unknown);
+    readonly originalError: unknown;
+    readonly gitOutput?: GitProcessOutput;
+    constructor(message: string, originalError?: unknown, gitOutput?: GitProcessOutput);
 }
 export type GitProcessOutput = {
     stderr: string;
@@ -22,20 +28,34 @@ export declare function addGitObserver(observer: GitObserver): () => void;
 /** Clear all git observers */
 export declare function clearGitObservers(): void;
 /**
- * Runs git command - use this for read-only commands.
- * `gitFailFast` is recommended for commands that make changes to the filesystem.
+ * Runs git command - use this for read-only commands, or if you'd like to explicitly check the
+ * result and implement custom error handling.
  *
  * The caller is responsible for validating the input.
  * `shell` will always be set to false.
  */
-export declare function git(args: string[], options?: SpawnSyncOptions): GitProcessOutput;
+export declare function git(args: string[], options?: GitOptions): GitProcessOutput;
 /**
- * Runs git command and throws an error if it fails.
- * Use this for commands that make changes to the filesystem.
+ * Run a git command. Use this for commands that make critical changes to the filesystem.
+ * If it fails, throw an error and set `process.exitCode = 1` (unless `options.noExitCode` is set).
  *
  * The caller is responsible for validating the input.
  * `shell` will always be set to false.
  */
-export declare function gitFailFast(args: string[], options?: SpawnSyncOptions & {
+export declare function gitFailFast(args: string[], options?: GitCommonOptions & {
     noExitCode?: boolean;
 }): void;
+/**
+ * Processes git command output by splitting it into lines and filtering out empty lines.
+ * Also filters out `node_modules` lines if specified in options.
+ *
+ * If the command failed with stderr output, an error is thrown.
+ *
+ * @param output - The git command output to process
+ * @returns An array of lines (presumably file paths), or an empty array if the command failed
+ * without stderr output.
+ * @internal
+ */
+export declare function processGitOutput(output: GitProcessOutput, options?: {
+    excludeNodeModules?: boolean;
+}): string[];

package/lib/git/git.js

@@ -3,17 +3,21 @@
 // Basic git wrappers
 //
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitFailFast = exports.git = exports.clearGitObservers = exports.addGitObserver = exports.GitError = void 0;
+exports.processGitOutput = exports.gitFailFast = exports.git = exports.clearGitObservers = exports.addGitObserver = exports.GitError = void 0;
 const child_process_1 = require("child_process");
 class GitError extends Error {
-    constructor(message, originalError) {
+    constructor(message, originalError, gitOutput) {
         if (originalError instanceof Error) {
             super(`${message}: ${originalError.message}`);
         }
+        else if (gitOutput?.stderr) {
+            super(`${message} -- stderr:\n${gitOutput.stderr}`);
+        }
         else {
             super(message);
         }
         this.originalError = originalError;
+        this.gitOutput = gitOutput;
     }
 }
 exports.GitError = GitError;
@@ -48,19 +52,28 @@ function removeGitObserver(observer) {
     }
 }
 /**
- * Runs git command - use this for read-only commands.
- * `gitFailFast` is recommended for commands that make changes to the filesystem.
+ * Runs git command - use this for read-only commands, or if you'd like to explicitly check the
+ * result and implement custom error handling.
  *
  * The caller is responsible for validating the input.
  * `shell` will always be set to false.
  */
 function git(args, options) {
-    isDebug && console.log(`git ${args.join(" ")}`);
     if (args.some((arg) => arg.startsWith("--upload-pack"))) {
         // This is a security issue and not needed for any expected usage of this library.
         throw new GitError("git command contains --upload-pack, which is not allowed: " + args.join(" "));
     }
-    const results = (0, child_process_1.spawnSync)("git", args, { maxBuffer: defaultMaxBuffer, ...options, shell: false });
+    const gitDescription = `git ${args.join(" ")}`;
+    const { throwOnError, description = gitDescription, debug = isDebug, ...spawnOptions } = options || {};
+    debug && console.log(gitDescription);
+    let results;
+    try {
+        // this only throws if git isn't found or other rare cases
+        results = (0, child_process_1.spawnSync)("git", args, { maxBuffer: defaultMaxBuffer, ...spawnOptions });
+    }
+    catch (e) {
+        throw new GitError(`${description} failed (while spawning process)`, e);
+    }
     const output = {
         ...results,
         // these may be undefined if stdio: inherit is set
@@ -68,7 +81,7 @@ function git(args, options) {
         stdout: (results.stdout || "").toString().trimEnd(),
         success: results.status === 0,
     };
-    if (isDebug) {
+    if (debug) {
         console.log("exited with code " + results.status);
         output.stdout && console.log("git stdout:\n", output.stdout);
         output.stderr && console.warn("git stderr:\n", output.stderr);
@@ -81,12 +94,15 @@ function git(args, options) {
         }
         observing = false;
     }
+    if (!output.success && throwOnError) {
+        throw new GitError(`${description} failed${output.stderr ? `\n${output.stderr}` : ""}`, undefined, output);
+    }
     return output;
 }
 exports.git = git;
 /**
- * Runs git command and throws an error if it fails.
- * Use this for commands that make changes to the filesystem.
+ * Run a git command. Use this for commands that make critical changes to the filesystem.
+ * If it fails, throw an error and set `process.exitCode = 1` (unless `options.noExitCode` is set).
  *
  * The caller is responsible for validating the input.
  * `shell` will always be set to false.
@@ -103,4 +119,26 @@ function gitFailFast(args, options) {
     }
 }
 exports.gitFailFast = gitFailFast;
+/**
+ * Processes git command output by splitting it into lines and filtering out empty lines.
+ * Also filters out `node_modules` lines if specified in options.
+ *
+ * If the command failed with stderr output, an error is thrown.
+ *
+ * @param output - The git command output to process
+ * @returns An array of lines (presumably file paths), or an empty array if the command failed
+ * without stderr output.
+ * @internal
+ */
+function processGitOutput(output, options) {
+    if (!output.success) {
+        // If the intent was to throw on failure, `throwOnError` should have been set for the git command.
+        return [];
+    }
+    return output.stdout
+        .split(/\n/)
+        .map((line) => line.trim())
+        .filter((line) => !!line && (!options?.excludeNodeModules || !line.includes("node_modules")));
+}
+exports.processGitOutput = processGitOutput;
 //# sourceMappingURL=git.js.map

package/lib/git/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/git/git.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/git/git.ts"],"names":[],"mappings":"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"}

package/lib/git/gitUtilities.d.ts

@@ -1,142 +1,170 @@
+import type { GetChangesBetweenRefsOptions, GitBranchOptions, GitCommitOptions, GitCommonOptions, GitFetchOptions, GitInitOptions, GitStageOptions, ParsedRemoteBranch, ParseRemoteBranchOptions } from "./types";
 /**
  * Get a list of files with untracked changes.
- * Throws an error on failure.
+ * Throws an error on failure by default.
  *
  * @returns An array of file paths with untracked changes
  */
+export declare function getUntrackedChanges(options: GitCommonOptions): string[];
+/** @deprecated Use object params version */
 export declare function getUntrackedChanges(cwd: string): string[];
 /**
- * Fetch from the given remote.
- * Throws an error on failure.
+ * Fetch from the given remote (and optionally branch) or all remotes.
+ * Throws an error on failure by default.
  */
+export declare function fetchRemote(options: GitFetchOptions): void;
+/** @deprecated Use object params version */
 export declare function fetchRemote(remote: string, cwd: string): void;
 /**
- * Fetch from the given remote and branch.
- * Throws an error on failure.
+ * Fetch from the given remote and branch. Throws an error on failure.
+ * @deprecated Use `fetchRemote({ remote, remoteBranch, cwd })`
  */
 export declare function fetchRemoteBranch(remote: string, remoteBranch: string, cwd: string): void;
 /**
  * Gets file paths with changes that have not been staged yet.
- * Throws an error on failure.
+ * Throws an error on failure by default.
  *
  * @returns An array of relative file paths with unstaged changes
  */
+export declare function getUnstagedChanges(options: GitCommonOptions): string[];
+/** @deprecated Use object params version */
 export declare function getUnstagedChanges(cwd: string): string[];
 /**
  * Gets file paths with changes between the current branch and the given branch.
  * Throws an error on failure.
  *
  * @returns An array of relative file paths that have changed
+ * @deprecated Use `getBranchChanges({ branch, cwd })`
  */
 export declare function getChanges(branch: string, cwd: string): string[];
 /**
  * Gets file paths with changes between the branch and the merge-base.
+ * Throws an error on failure by default.
  *
  * @returns An array of relative file paths that have changed
  */
+export declare function getBranchChanges(options: GitBranchOptions): string[];
+/** @deprecated Use object params version */
 export declare function getBranchChanges(branch: string, cwd: string): string[];
 /**
  * Gets file paths with changes between two git references (commits, branches, tags).
- * Throws an error on failure.
+ * Throws an error on failure by default.
  *
- * @param fromRef - The starting reference
- * @param toRef - The ending reference
- * @param options - Additional git diff options
- * @param pattern - Optional file pattern to filter results
- * @param cwd - The working directory
  * @returns An array of file paths that have changed
  */
+export declare function getChangesBetweenRefs(options: GetChangesBetweenRefsOptions): string[];
+/** @deprecated Use object param version */
 export declare function getChangesBetweenRefs(fromRef: string, toRef: string, options: string[], pattern: string, cwd: string): string[];
 /**
  * Gets all files with staged changes (files added to the index).
- * Throws an error on failure.
+ * Throws an error on failure by default.
  *
  * @returns An array of relative file paths that have been staged
  */
+export declare function getStagedChanges(options: GitCommonOptions): string[];
+/** @deprecated Use object params version */
 export declare function getStagedChanges(cwd: string): string[];
 /**
- * Gets recent commit messages between the specified branch and HEAD.
- * Returns an empty array if the operation fails.
+ * Gets recent commit messages between the specified parent branch and HEAD.
+ * By default, returns an empty array if the operation fails.
  *
  * @returns An array of commit message strings
  */
+export declare function getRecentCommitMessages(options: GitBranchOptions): string[];
+/** @deprecated Use object params version */
 export declare function getRecentCommitMessages(branch: string, cwd: string): string[];
 /**
  * Gets the user email from the git config.
  * @returns The email string if found, null otherwise
  */
+export declare function getUserEmail(options: GitCommonOptions): string | null;
+/** @deprecated Use object params version */
 export declare function getUserEmail(cwd: string): string | null;
 /**
  * Gets the current branch name.
+ * In detached HEAD state, returns "HEAD".
+ *
  * @returns The branch name if successful, null otherwise
  */
-export declare function getBranchName(cwd: string): string | null;
+export declare function getBranchName(options: GitCommonOptions): string;
+/** @deprecated Use object params version */
+export declare function getBranchName(cwd: string): string;
 /**
  * Gets the full reference path for a given branch.
- * @param branch - The short branch name (e.g., `branch-name`)
+ * `branch` here is the short branch name, e.g. `branch-name`.
  * @returns The full branch reference (e.g., `refs/heads/branch-name`) if found, null otherwise
  */
+export declare function getFullBranchRef(options: GitBranchOptions): string | null;
+/** @deprecated Use object params version */
 export declare function getFullBranchRef(branch: string, cwd: string): string | null;
 /**
  * Gets the short branch name from a full branch reference.
- * Note this may not work properly for the current branch.
- * @param fullBranchRef - The full branch reference (e.g., `refs/heads/branch-name`)
  * @returns The short branch name if successful, null otherwise
  */
+export declare function getShortBranchName(options: {
+    /** The full branch reference (e.g., `refs/heads/branch-name`) */
+    fullBranchRef: string;
+} & GitCommonOptions): string | null;
+/** @deprecated Use object params version */
 export declare function getShortBranchName(fullBranchRef: string, cwd: string): string | null;
 /**
  * Gets the current commit hash (SHA).
  * @returns The hash if successful, null otherwise
  */
+export declare function getCurrentHash(options: GitCommonOptions): string | null;
+/** @deprecated Use object params version */
 export declare function getCurrentHash(cwd: string): string | null;
 /**
  * Get the commit hash in which the file was first added.
  * @returns The commit hash if found, undefined otherwise
  */
+export declare function getFileAddedHash(options: {
+    filename: string;
+} & GitCommonOptions): string | undefined;
+/** @deprecated Use object params version */
 export declare function getFileAddedHash(filename: string, cwd: string): string | undefined;
 /**
- * Initializes a git repository in the specified directory.
- * Optionally sets user email and username if not already configured.
- * Throws an error if required email or username is not provided and not already configured.
+ * Run `git init` and verify that the `user.name` and `user.email` configs are set (at any level).
+ * Throws an error if `git init` fails.
  *
- * @param cwd - The directory to initialize the git repository in
- * @param email - Optional email to set in git config
- * @param username - Optional username to set in git config
+ * If `user.email` and `user.name` aren't already set globally, and the missing value is provided
+ * in params, set it at the repo level. Otherwise, throw an error.
  */
+export declare function init(options: GitInitOptions): void;
+/** @deprecated Use object params version */
 export declare function init(cwd: string, email?: string, username?: string): void;
 /**
  * Stages files matching the given patterns.
  */
+export declare function stage(options: GitStageOptions): void;
+/** @deprecated Use object params version */
 export declare function stage(patterns: string[], cwd: string): void;
 /**
- * Creates a commit with the given message and optional git commit options.
- * Throws an error on failure.
- *
- * @param message - The commit message
- * @param cwd - The working directory
- * @param options - Additional git commit options
+ * Commit changes. Throws an error on failure by default.
  */
+export declare function commit(options: GitCommitOptions): void;
+/** @deprecated Use object params version */
 export declare function commit(message: string, cwd: string, options?: string[]): void;
 /**
  * Stages files matching the given patterns and creates a commit with the specified message.
  * Convenience function that combines `stage()` and `commit()`.
- * Throws an error on commit failure.
- *
- * @param patterns - File patterns to stage
- * @param message - The commit message
- * @param cwd - The working directory
- * @param commitOptions - Additional git commit options
+ * Throws an error on commit failure by default.
  */
+export declare function stageAndCommit(options: GitStageOptions & GitCommitOptions): void;
+/** @deprecated Use object params version */
 export declare function stageAndCommit(patterns: string[], message: string, cwd: string, commitOptions?: string[]): void;
 /**
  * Reverts all local changes (both staged and unstaged) by stashing them and then dropping the stash.
- * @returns True if the revert was successful, false otherwise
+ * @returns True if the revert was successful, false otherwise. It will also be false if there were
+ * no changes to revert. (To distinguish between this case and errors, use the `throwOnError` option.)
  */
+export declare function revertLocalChanges(options: GitCommonOptions): boolean;
+/** @deprecated Use object params version */
 export declare function revertLocalChanges(cwd: string): boolean;
 /**
  * Attempts to determine the parent branch of the current branch using `git show-branch`.
- *
  * @returns The parent branch name if found, null otherwise
+ * @deprecated Does not appear to be used
  */
 export declare function getParentBranch(cwd: string): string | null;
 /**
@@ -144,27 +172,37 @@ export declare function getParentBranch(cwd: string): string | null;
  *
  * @returns The remote branch name (e.g., `origin/main`) if found, null otherwise
  */
+export declare function getRemoteBranch(options: GitBranchOptions): string | null;
+/** @deprecated Use object params version */
 export declare function getRemoteBranch(branch: string, cwd: string): string | null;
 /**
- * Parses a remote branch string (e.g., `origin/main`) into its components.
+ * Get the remote and branch name from a full branch name that may include a remote prefix.
+ * If the path doesn't start with one of `options.knownRemotes` (but has multiple segments),
+ * the actual list of remotes will be fetched to see if one of those matches.
  *
- * @param branch - The remote branch string to parse (e.g., `origin/main`)
+ * NOTE: The additional verification is new in the object params version; the original version
+ * incorrectly assumes the first segment before a slash is always a remote.
  */
-export declare function parseRemoteBranch(branch: string): {
-    /** Remote name, e.g. `origin` */
-    remote: string;
-    /** Remote branch name, e.g. `main` */
-    remoteBranch: string;
-};
+export declare function parseRemoteBranch(options: ParseRemoteBranchOptions): ParsedRemoteBranch;
+/**
+ * @deprecated Use object params version, which does more verification. This version inaccurately
+ * assumes the first segment before a slash is always a remote, which could lead to tricky bugs.
+ */
+export declare function parseRemoteBranch(branch: string): ParsedRemoteBranch;
 /**
  * Gets the default branch based on `git config init.defaultBranch`, falling back to `master`.
  */
+export declare function getDefaultBranch(options: GitCommonOptions): string;
+/** @deprecated Use object params version */
 export declare function getDefaultBranch(cwd: string): string;
 /**
  * Lists all tracked files matching the given patterns.
- *
- * @param patterns - File patterns to match (passed to git ls-files)
- * @param cwd - The working directory
+ * Throws on error by default.
  * @returns An array of file paths, or an empty array if no files are found
  */
+export declare function listAllTrackedFiles(options: {
+    /** File patterns to match (passed to git ls-files) */
+    patterns: string[];
+} & GitCommonOptions): string[];
+/** @deprecated Use object params version */
 export declare function listAllTrackedFiles(patterns: string[], cwd: string): string[];