feat: add 'create' operation to stash API (#2211) fix #2207

* feat: add 'create' operation to stash API, allowing stash commits without modifying working directory

* docs: add @anish3333 as a contributor

* refactor: improve readability of stash create tests by using consistent variable declarations and formatting

* fix: format changed files with Prettier and ESLint

* refactor: extract common stash commit logic to _createStashCommit

Author: anish3333

docs/en/next/stash.html

@@ -392,7 +392,10 @@ Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds
     <td align="center"><a href="https://github.com/gnillev"><img src="https://avatars.githubusercontent.com/u/8965094?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mathias Nisted Velling</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=gnillev" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=gnillev" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/acandoo"><img src="https://avatars.githubusercontent.com/u/117209328?v=4?s=60" width="60px;" alt=""/><br /><sub><b>acandoo</b></sub></a><br /><a href="#platform-acandoo" title="Packaging/porting to new platform">📦</a> <a href="#userTesting-acandoo" title="User Testing">📓</a></td>
     <td align="center"><a href="https://github.com/bekatan"><img src="https://avatars.githubusercontent.com/u/19550476?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Bekatan Satyev</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=bekatan" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=bekatan" title="Tests">⚠️</a></td>
+  </tr>
+  <tr>
     <td align="center"><a href="https://github.com/hemanthkini"><img src="https://avatars.githubusercontent.com/u/3934055?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Hemanth Kini</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=hemanthkini" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/anish3333"><img src="https://avatars.githubusercontent.com/u/128889867?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Anish Awasthi</b></sub></a><br /><a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Code">💻</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Documentation">📖</a> <a href="https://github.com/isomorphic-git/isomorphic-git/commits?author=anish3333" title="Tests">⚠️</a></td>
   </tr>
 </table>
 

docs/en/next/stash/index.html

@@ -15013,16 +15013,19 @@ class GitStashManager {
       return []
     }
 
-    const reflogBuffer = await this.fs.read(this.refLogsStashPath);
-    const reflogString = reflogBuffer.toString();
+    const reflogString = await this.fs.read(this.refLogsStashPath, 'utf8');
 
     return GitRefStash.getStashReflogEntry(reflogString, parsed)
   }
 }
 
 // @ts-check
 
-async function _stashPush({ fs, dir, gitdir, message = '' }) {
+/**
+ * Common logic for creating a stash commit
+ * @private
+ */
+async function _createStashCommit({ fs, dir, gitdir, message = '' }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
   await stashMgr.getAuthor(); // ensure there is an author
@@ -15057,7 +15060,7 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     // create a commit from the index tree, which has one parent, the current branch HEAD
     const stashCommitOne = await stashMgr.writeStashCommit({
       message: `stash-Index: WIP on ${branch} - ${new Date().toISOString()}`,
-      tree: indexTree, // stashCommitTree
+      tree: indexTree,
       parent: stashCommitParents,
     });
     stashCommitParents.push(stashCommitOne);
@@ -15098,6 +15101,17 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     parent: stashCommitParents,
   });
 
+  return { stashCommit, stashMsg, branch, stashMgr }
+}
+
+async function _stashPush({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit, stashMsg, branch, stashMgr } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
   // next, write this commit into .git/refs/stash:
   await stashMgr.writeStashRef(stashCommit);
 
@@ -15120,6 +15134,18 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
   return stashCommit
 }
 
+async function _stashCreate({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
+  // Return the stash commit hash without modifying refs or working directory
+  return stashCommit
+}
+
 async function _stashApply({ fs, dir, gitdir, refIdx = 0 }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
@@ -15223,21 +15249,22 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
 // @ts-check
 
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -15272,6 +15299,10 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 
 async function stash({
@@ -15294,6 +15325,7 @@ async function stash({
     list: _stashList,
     clear: _stashClear,
     pop: _stashPop,
+    create: _stashCreate,
   };
 
   const opsNeedRefIdx = ['apply', 'drop', 'pop'];

docs/en/stash.html

@@ -3033,21 +3033,22 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
     append?: boolean | undefined;
 }): Promise<void>;
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -3082,12 +3083,16 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 export function stash({ fs, dir, gitdir, op, message, refIdx, }: {
     fs: FsClient;
     dir?: string | undefined;
     gitdir?: string | undefined;
-    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | undefined;
+    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | "create" | undefined;
     message?: string | undefined;
     refIdx?: number | undefined;
 }): Promise<string | void>;

docs/en/stash/index.html

@@ -3032,21 +3032,22 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
     append?: boolean | undefined;
 }): Promise<void>;
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -3081,12 +3082,16 @@ export function setConfig({ fs: _fs, dir, gitdir, path, value, append, }: {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 export function stash({ fs, dir, gitdir, op, message, refIdx, }: {
     fs: FsClient;
     dir?: string | undefined;
     gitdir?: string | undefined;
-    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | undefined;
+    op?: "pop" | "push" | "clear" | "drop" | "apply" | "list" | "create" | undefined;
     message?: string | undefined;
     refIdx?: number | undefined;
 }): Promise<string | void>;

js/isomorphic-git/README.md

@@ -15007,16 +15007,19 @@ class GitStashManager {
       return []
     }
 
-    const reflogBuffer = await this.fs.read(this.refLogsStashPath);
-    const reflogString = reflogBuffer.toString();
+    const reflogString = await this.fs.read(this.refLogsStashPath, 'utf8');
 
     return GitRefStash.getStashReflogEntry(reflogString, parsed)
   }
 }
 
 // @ts-check
 
-async function _stashPush({ fs, dir, gitdir, message = '' }) {
+/**
+ * Common logic for creating a stash commit
+ * @private
+ */
+async function _createStashCommit({ fs, dir, gitdir, message = '' }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
   await stashMgr.getAuthor(); // ensure there is an author
@@ -15051,7 +15054,7 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     // create a commit from the index tree, which has one parent, the current branch HEAD
     const stashCommitOne = await stashMgr.writeStashCommit({
       message: `stash-Index: WIP on ${branch} - ${new Date().toISOString()}`,
-      tree: indexTree, // stashCommitTree
+      tree: indexTree,
       parent: stashCommitParents,
     });
     stashCommitParents.push(stashCommitOne);
@@ -15092,6 +15095,17 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
     parent: stashCommitParents,
   });
 
+  return { stashCommit, stashMsg, branch, stashMgr }
+}
+
+async function _stashPush({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit, stashMsg, branch, stashMgr } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
   // next, write this commit into .git/refs/stash:
   await stashMgr.writeStashRef(stashCommit);
 
@@ -15114,6 +15128,18 @@ async function _stashPush({ fs, dir, gitdir, message = '' }) {
   return stashCommit
 }
 
+async function _stashCreate({ fs, dir, gitdir, message = '' }) {
+  const { stashCommit } = await _createStashCommit({
+    fs,
+    dir,
+    gitdir,
+    message,
+  });
+
+  // Return the stash commit hash without modifying refs or working directory
+  return stashCommit
+}
+
 async function _stashApply({ fs, dir, gitdir, refIdx = 0 }) {
   const stashMgr = new GitStashManager({ fs, dir, gitdir });
 
@@ -15217,21 +15243,22 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
 // @ts-check
 
 /**
- * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} StashOp
+ * stash api, supports  {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} StashOp
  * _note_,
  * - all stash operations are done on tracked files only with loose objects, no packed objects
  * - when op === 'push', both working directory and index (staged) changes will be stashed, tracked files only
  * - when op === 'push', message is optional, and only applicable when op === 'push'
  * - when op === 'apply | pop', the stashed changes will overwrite the working directory, no abort when conflicts
+ * - when op === 'create', creates a stash commit without modifying working directory or refs, returns the commit hash
  *
  * @param {object} args
  * @param {FsClient} args.fs - [required] a file system client
  * @param {string} [args.dir] - [required] The [working tree](dir-vs-gitdir.md) directory path
  * @param {string} [args.gitdir=join(dir,'.git')] - [optional] The [git directory](dir-vs-gitdir.md) path
- * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
- * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push'
+ * @param {'push' | 'pop' | 'apply' | 'drop' | 'list' | 'clear' | 'create'} [args.op = 'push'] - [optional] name of stash operation, default to 'push'
+ * @param {string} [args.message = ''] - [optional] message to be used for the stash entry, only applicable when op === 'push' or 'create'
  * @param {number} [args.refIdx = 0] - [optional - Number] stash ref index of entry, only applicable when op === ['apply' | 'drop' | 'pop'], refIdx >= 0 and < num of stash pushed
- * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete
+ * @returns {Promise<string | void>}  Resolves successfully when stash operations are complete. Returns commit hash for 'create' operation.
  *
  * @example
  * // stash changes in the working directory and index
@@ -15266,6 +15293,10 @@ async function _stashPop({ fs, dir, gitdir, refIdx = 0 }) {
  *
  * console.log(await git.status({ fs, dir, filepath: 'a.txt' })) // 'modified'
  * console.log(await git.status({ fs, dir, filepath: 'b.txt' })) // '*modified'
+ *
+ * // create a stash commit without modifying working directory
+ * const stashCommitHash = await git.stash({ fs, dir, op: 'create', message: 'my stash' })
+ * console.log(stashCommitHash) // returns the stash commit hash
  */
 
 async function stash({
@@ -15288,6 +15319,7 @@ async function stash({
     list: _stashList,
     clear: _stashClear,
     pop: _stashPop,
+    create: _stashCreate,
   };
 
   const opsNeedRefIdx = ['apply', 'drop', 'pop'];