exec-staged 0.1.3 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ Run commands against files staged in git, ignoring unstaged changes and untracke
 
 ### How it Works
 
-1. Unstaged changes and untracked files are hidden in a git stash. This inludes unstaged deletions, which are temporarily restored.
+1. Unstaged changes and untracked files are hidden in a git stash. This includes unstaged deletions, which are temporarily restored.
 2. User-configured tasks are run, with staged files passed in according to configuration.
 3. Any changes made by tasks are added to the git index. This includes additions and deletions.
 4. The stashed changes are restored.
@@ -131,7 +131,7 @@ Commands which include the `$FILES` token are only run if staged files are found
 
 File filtering can be customized.
 
-To filter files by name, add a `glob` filter (defaults to `'*'`):
+To filter files by name, add a `glob` filter (defaults to `'**'`):
 
 ```typescript
 { task: 'prettier --write $FILES', glob: '*.{js,ts,json,md}' }
@@ -155,21 +155,15 @@ Before running any potentially destructive scripts, `exec-staged` stores all out
 
 ### Recovery
 
-If `exec-staged` fails to exit safely, such as due to power loss or if its process is killed via `SIGKILL`, its backup stash should still be present.
-
-To verify, run `git log` and look for a stash with the message `💾 exec-staged backup stash`. It should be the most recent stash. If it isn't, one of your tasks probably created a stash for some reason. This is very unlikely. Remove any such stashes before proceeding.
-
-`exec-staged` also creates a short-lived temporary commit with the message `💾 exec-staged staged changes`. If it's present, it can be removed with `git reset --hard HEAD~1`.
-
-The following commands should return your repository to its original state:
+If `exec-staged` fails to exit safely, such as due to power loss or if its process is killed via `SIGKILL`, run the recovery tool to restore your repository to its original state:
 
 ```bash
-git add -A
-git reset --hard HEAD
-git stash pop --index
+npx exec-staged recover
 ```
 
-To prevent data loss, `exec-staged` will not run if a stash or commit from a previous run is present.
+This will automatically find and apply the backup stash, restore any merge metadata, and clean up leftover artifacts.
+
+To prevent data loss, `exec-staged` will not run if artifacts from a previous run are present.
 
 ## See Also
 

package/dist/bin/cli.js

@@ -1,19 +1,33 @@
 #!/usr/bin/env node
 import pkg from '../../package.json' with { type: 'json' };
 import { loadConfig } from '../lib/config.js';
-import { execStaged } from '../lib/exec_staged.js';
+import { execStaged, recoverStaged } from '../lib/exec_staged.js';
 import { program } from 'commander';
 import path from 'node:path';
 program.name(pkg.name).version(pkg.version).description(pkg.description);
 program.option('--quiet', 'suppress output');
 program.option('--cwd <cwd>', 'directory in which to run');
-program.argument('[tasks...]');
+program
+    .command('run', { isDefault: true })
+    .argument('[tasks...]')
+    .action(async (args) => {
+    const options = program.opts();
+    const cwd = path.resolve(options.cwd ?? '');
+    const tasks = args.length ? args : await loadConfig(cwd);
+    const result = await execStaged(cwd, tasks, options);
+    if (!result) {
+        process.exitCode ||= 1;
+    }
+});
+program
+    .command('recover')
+    .description('Recover from a failed exec-staged run')
+    .action(() => {
+    const options = program.opts();
+    const cwd = path.resolve(options.cwd ?? '');
+    const result = recoverStaged(cwd);
+    if (!result) {
+        process.exitCode ||= 1;
+    }
+});
 program.parse(process.argv);
-const options = program.opts();
-const args = program.args;
-const cwd = path.resolve(options.cwd ?? '');
-const tasks = args.length ? args : await loadConfig(cwd);
-const result = await execStaged(cwd, tasks, options);
-if (!result) {
-    process.exitCode ||= 1;
-}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { execStaged } from './lib/exec_staged.js';
+import { execStaged, recoverStaged } from './lib/exec_staged.js';
 export default execStaged;
+export { recoverStaged };

package/dist/index.js

@@ -1,2 +1,3 @@
-import { execStaged } from './lib/exec_staged.js';
+import { execStaged, recoverStaged } from './lib/exec_staged.js';
 export default execStaged;
+export { recoverStaged };

package/dist/lib/constants.d.ts

@@ -3,6 +3,7 @@ export declare const DEFAULT_CONFIG_ENTRY: Omit<ExecStagedConfigEntry, 'task'>;
 export declare const MERGE_FILES: readonly ["MERGE_HEAD", "MERGE_MODE", "MERGE_MSG"];
 export declare const BACKUP_STASH_MESSAGE: string;
 export declare const STAGED_CHANGES_COMMIT_MESSAGE: string;
+export declare const ARTIFACTS_DIRECTORY: string;
 export declare const INTERPOLATION_IDENTIFIER = "$FILES";
 export declare const stageLifecycleMessages: {
     check: string;

package/dist/lib/constants.js

@@ -6,6 +6,7 @@ export const DEFAULT_CONFIG_ENTRY = {
 export const MERGE_FILES = ['MERGE_HEAD', 'MERGE_MODE', 'MERGE_MSG'];
 export const BACKUP_STASH_MESSAGE = `💾 ${pkg.name} backup stash`;
 export const STAGED_CHANGES_COMMIT_MESSAGE = `💾 ${pkg.name} staged changes`;
+export const ARTIFACTS_DIRECTORY = `.${pkg.name}`;
 export const INTERPOLATION_IDENTIFIER = '$FILES';
 const PREFIX = '➡️ ';
 export const stageLifecycleMessages = {

package/dist/lib/exec_staged.d.ts

@@ -1,2 +1,3 @@
 import type { ExecStagedUserConfig, StageOptions } from '../types.js';
 export declare const execStaged: (cwd: string, tasks: ExecStagedUserConfig, options?: StageOptions) => Promise<boolean>;
+export declare const recoverStaged: (cwd: string) => boolean;

package/dist/lib/exec_staged.js

@@ -13,3 +13,14 @@ export const execStaged = async (cwd, tasks, options = {}) => {
         return false;
     }
 };
+export const recoverStaged = (cwd) => {
+    const stage = new Stage(cwd);
+    try {
+        stage.recover();
+        return true;
+    }
+    catch (error) {
+        console.log(`🪲 Log saved to: ${stage.logger.outFile}`);
+        return false;
+    }
+};

package/dist/lib/stage.d.ts

@@ -7,8 +7,10 @@ export declare class Stage {
     private readonly status;
     private readonly mergeStatus;
     private head?;
-    private patchPath?;
-    private gitDir?;
+    private _gitDir?;
+    private get gitDir();
+    private get artifactsDir();
+    private get patchPath();
     constructor(cwd: string, options?: StageOptions);
     exec(tasks: ExecStagedConfig): Promise<void>;
     protected check(): void;
@@ -21,4 +23,5 @@ export declare class Stage {
     private restoreMergeStatus;
     private indexOfBackupStash;
     private findBackupStash;
+    recover(): void;
 }

package/dist/lib/stage.js

@@ -1,4 +1,4 @@
-import { BACKUP_STASH_MESSAGE, INTERPOLATION_IDENTIFIER, MERGE_FILES, STAGED_CHANGES_COMMIT_MESSAGE, stageLifecycleMessages, } from './constants.js';
+import { ARTIFACTS_DIRECTORY, BACKUP_STASH_MESSAGE, INTERPOLATION_IDENTIFIER, MERGE_FILES, STAGED_CHANGES_COMMIT_MESSAGE, stageLifecycleMessages, } from './constants.js';
 import { Logger } from './logger.js';
 import { spawn, spawnSync } from './spawn.js';
 import micromatch from 'micromatch';
@@ -11,10 +11,18 @@ export class Stage {
     cwd;
     stashed = false;
     status = {};
-    mergeStatus = {};
+    mergeStatus = [];
     head;
-    patchPath;
-    gitDir;
+    _gitDir;
+    get gitDir() {
+        return (this._gitDir ??= this.git(['rev-parse', '--absolute-git-dir']));
+    }
+    get artifactsDir() {
+        return path.resolve(this.gitDir, ARTIFACTS_DIRECTORY);
+    }
+    get patchPath() {
+        return path.resolve(this.artifactsDir, 'patch.diff');
+    }
     constructor(cwd, options = {}) {
         this.cwd = cwd;
         this.logger = new Logger(options.quiet);
@@ -56,7 +64,7 @@ export class Stage {
         }
         catch (error) {
             this.logger.log('⚠️ Git installation not found!');
-            throw error;
+            throw new Error('git installation not found');
         }
         if (!version || semver.lte(version, '2.13.0')) {
             this.logger.log('⚠️ Unsupported git version!');
@@ -74,12 +82,32 @@ export class Stage {
             this.logger.log('⚠️ Not in git root directory!');
             throw new Error('cwd is not a git repository root directory');
         }
+        // --absolute-git-dir resolves symlinks, --git-dir does not; if they
+        // differ, .git involves symlinks; walk the chain and reject if any
+        // target is inside the repo, because git stash --include-untracked
+        // would stash (and remove) it, breaking all subsequent operations
+        let gitDirPath = path.resolve(this.cwd, this.git(['rev-parse', '--git-dir']));
+        while (fs.lstatSync(gitDirPath).isSymbolicLink()) {
+            // readlink may return a relative path, so resolve against the
+            // symlink's parent directory to get an absolute path
+            const target = fs.readlinkSync(gitDirPath);
+            gitDirPath = path.resolve(path.dirname(gitDirPath), target);
+            if (!path.relative(this.cwd, gitDirPath).startsWith('..')) {
+                this.logger.log('⚠️ Git directory is a symlink pointing to a location within the repository!');
+                throw new Error('git directory is a symlink pointing to a location within the repository');
+            }
+        }
+        if (fs.existsSync(this.artifactsDir)) {
+            this.logger.log('⚠️ Found unexpected artifacts directory!');
+            this.logger.log('It must be left over from a previous failed run.  Run `exec-staged recover` to restore your repository.');
+            throw new Error('unexpected artifacts directory');
+        }
         if (this.indexOfBackupStash() !== -1) {
             this.logger.log('⚠️ Found unexpected backup stash!');
-            this.logger.log('It must be left over from a previous failed run.  Remove it before proceeding.');
+            this.logger.log('It must be left over from a previous failed run.  Run `exec-staged recover` to restore your repository.');
             throw new Error('unexpected backup stash');
         }
-        if (this.git(['log']).includes(STAGED_CHANGES_COMMIT_MESSAGE)) {
+        if (this.git(['log', '--grep', STAGED_CHANGES_COMMIT_MESSAGE, '--format=%s'])) {
             this.logger.log('⚠️ Found unexpected temporary commit!');
             this.logger.log('It must be left over from a previous failed run.  Remove it before proceeding.');
             throw new Error('unexpected temporary commit');
@@ -88,8 +116,6 @@ export class Stage {
     prepare() {
         this.logger.log(stageLifecycleMessages.prepare);
         this.head = this.git(['rev-parse', 'HEAD']);
-        this.gitDir = this.git(['rev-parse', '--absolute-git-dir']);
-        this.patchPath = path.resolve(this.gitDir, 'patch.diff');
         this.git(['status', '--porcelain', '--no-renames'])
             .split('\n')
             .filter((f) => f.length)
@@ -97,6 +123,7 @@ export class Stage {
         // if there are no files in index or working tree, do not attempt to stash
         if (Object.keys(this.status).length === 0)
             return;
+        fs.mkdirSync(this.artifactsDir);
         try {
             this.logger.debug('➡️ ➡️ Creating patch of unstaged changes...');
             const unstagedAdditions = Object.entries(this.status)
@@ -164,7 +191,11 @@ export class Stage {
                 if (interpolationIndex !== -1) {
                     const files = micromatch(Object.entries(this.status)
                         .filter(([, s]) => s.match(new RegExp(`^[${diff}]`)))
-                        .map(([f]) => f), glob, { dot: true });
+                        .map(([f]) => f), glob, {
+                        dot: true,
+                        // match filenames in any directory when glob has no path separators
+                        matchBase: !glob.includes('/'),
+                    });
                     if (files.length === 0) {
                         this.logger.log(`➡️ No matching files, skipping task...`);
                         continue;
@@ -217,24 +248,25 @@ export class Stage {
             ]);
             // unstaged deletions are not included in the patch and must be handled
             // separately because the patch cannot be applied if such files are
-            // modified by tasks
+            // modified by tasks; use force: true to handle cases where the file
+            // doesn't exist (e.g., unstaged renames)
             Object.entries(this.status)
                 .filter(([, s]) => s.match(/^.D/))
                 .map(([f]) => f)
-                .forEach((f) => fs.rmSync(path.resolve(this.cwd, f)));
+                .forEach((f) => fs.rmSync(path.resolve(this.cwd, f), { force: true }));
             // make sure all restored unstaged changes are kept out of the index
             this.git(['reset']);
             // undo temporary commit while keeping its changes in the index
             this.git(['reset', '--soft', this.head]);
             // clean up
-            fs.rmSync(this.patchPath);
+            this.restoreMergeStatus();
+            fs.rmSync(this.artifactsDir, { recursive: true });
             this.git(['stash', 'drop', stash]);
         }
         catch (error) {
             this.logger.log('⚠️ Error restoring unstaged changes from stash!');
             throw error;
         }
-        this.restoreMergeStatus();
     }
     revert() {
         this.logger.log(stageLifecycleMessages.revert);
@@ -259,6 +291,7 @@ export class Stage {
             this.git(['stash', 'apply', '--index', stash]);
             this.git(['stash', 'drop', stash]);
             this.restoreMergeStatus();
+            fs.rmSync(this.artifactsDir, { recursive: true });
         }
         catch (error) {
             this.logger.log('⚠️ Failed to restore state from backup stash!');
@@ -273,16 +306,16 @@ export class Stage {
     }
     backupMergeStatus() {
         for (const mergeFile of MERGE_FILES) {
-            const file = path.resolve(this.gitDir, mergeFile);
-            if (fs.existsSync(file)) {
-                this.mergeStatus[mergeFile] = fs.readFileSync(file);
+            const src = path.resolve(this.gitDir, mergeFile);
+            if (fs.existsSync(src)) {
+                fs.copyFileSync(src, path.resolve(this.artifactsDir, mergeFile));
+                this.mergeStatus.push(mergeFile);
             }
         }
     }
     restoreMergeStatus() {
-        for (const mergeFile of Object.keys(this.mergeStatus)) {
-            const contents = this.mergeStatus[mergeFile];
-            fs.writeFileSync(path.resolve(this.gitDir, mergeFile), contents);
+        for (const mergeFile of this.mergeStatus) {
+            fs.renameSync(path.resolve(this.artifactsDir, mergeFile), path.resolve(this.gitDir, mergeFile));
         }
     }
     indexOfBackupStash() {
@@ -297,4 +330,32 @@ export class Stage {
         }
         return `stash@{${index}}`;
     }
+    recover() {
+        const stashIndex = this.indexOfBackupStash();
+        const stashFound = stashIndex !== -1;
+        const artifactsFound = fs.existsSync(this.artifactsDir);
+        if (!stashFound && !artifactsFound) {
+            this.logger.log('➡️ Nothing to recover.');
+            return;
+        }
+        if (stashFound) {
+            const stash = `stash@{${stashIndex}}`;
+            this.logger.log('➡️ Found backup stash, restoring...');
+            const head = this.git(['rev-parse', `${stash}^1`]);
+            this.git(['add', '-A']);
+            this.git(['reset', '--hard', head]);
+            this.git(['stash', 'apply', '--index', stash]);
+            this.git(['stash', 'drop', stash]);
+        }
+        if (artifactsFound) {
+            this.logger.log('➡️ Found artifacts directory, cleaning up...');
+            for (const mergeFile of MERGE_FILES) {
+                const src = path.resolve(this.artifactsDir, mergeFile);
+                if (fs.existsSync(src)) {
+                    fs.renameSync(src, path.resolve(this.gitDir, mergeFile));
+                }
+            }
+            fs.rmSync(this.artifactsDir, { recursive: true });
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exec-staged",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Run commands against the current git index",
   "keywords": [
     "git",

package/src/bin/cli.ts

@@ -1,26 +1,42 @@
 #!/usr/bin/env node
 import pkg from '../../package.json' with { type: 'json' };
 import { loadConfig } from '../lib/config.js';
-import { execStaged } from '../lib/exec_staged.js';
+import { execStaged, recoverStaged } from '../lib/exec_staged.js';
 import { program } from 'commander';
 import path from 'node:path';
 
 program.name(pkg.name).version(pkg.version).description(pkg.description);
 program.option('--quiet', 'suppress output');
 program.option('--cwd <cwd>', 'directory in which to run');
-program.argument('[tasks...]');
 
-program.parse(process.argv);
+program
+  .command('run', { isDefault: true })
+  .argument('[tasks...]')
+  .action(async (args: string[]) => {
+    const options = program.opts();
+    const cwd = path.resolve(options.cwd ?? '');
+
+    const tasks = args.length ? args : await loadConfig(cwd);
 
-const options = program.opts();
-const args = program.args;
+    const result = await execStaged(cwd, tasks, options);
 
-const cwd = path.resolve(options.cwd ?? '');
+    if (!result) {
+      process.exitCode ||= 1;
+    }
+  });
 
-const tasks = args.length ? args : await loadConfig(cwd);
+program
+  .command('recover')
+  .description('Recover from a failed exec-staged run')
+  .action(() => {
+    const options = program.opts();
+    const cwd = path.resolve(options.cwd ?? '');
 
-const result = await execStaged(cwd, tasks, options);
+    const result = recoverStaged(cwd);
 
-if (!result) {
-  process.exitCode ||= 1;
-}
+    if (!result) {
+      process.exitCode ||= 1;
+    }
+  });
+
+program.parse(process.argv);

package/src/index.ts

@@ -1,3 +1,4 @@
-import { execStaged } from './lib/exec_staged.js';
+import { execStaged, recoverStaged } from './lib/exec_staged.js';
 
 export default execStaged;
+export { recoverStaged };

package/src/lib/constants.ts

@@ -11,6 +11,8 @@ export const MERGE_FILES = ['MERGE_HEAD', 'MERGE_MODE', 'MERGE_MSG'] as const;
 export const BACKUP_STASH_MESSAGE = `💾 ${pkg.name} backup stash`;
 export const STAGED_CHANGES_COMMIT_MESSAGE = `💾 ${pkg.name} staged changes`;
 
+export const ARTIFACTS_DIRECTORY = `.${pkg.name}`;
+
 export const INTERPOLATION_IDENTIFIER = '$FILES';
 
 const PREFIX = '➡️ ';

package/src/lib/exec_staged.ts

@@ -19,3 +19,15 @@ export const execStaged = async (
     return false;
   }
 };
+
+export const recoverStaged = (cwd: string): boolean => {
+  const stage = new Stage(cwd);
+
+  try {
+    stage.recover();
+    return true;
+  } catch (error) {
+    console.log(`🪲 Log saved to: ${stage.logger.outFile}`);
+    return false;
+  }
+};

package/src/lib/stage.ts

@@ -1,5 +1,6 @@
 import type { ExecStagedConfig, StageOptions } from '../types.js';
 import {
+  ARTIFACTS_DIRECTORY,
   BACKUP_STASH_MESSAGE,
   INTERPOLATION_IDENTIFIER,
   MERGE_FILES,
@@ -19,12 +20,21 @@ export class Stage {
   protected readonly cwd: string;
   protected stashed: boolean = false;
   private readonly status: { [file: string]: string } = {};
-  private readonly mergeStatus: {
-    [file in (typeof MERGE_FILES)[number]]?: Buffer;
-  } = {};
+  private readonly mergeStatus: (typeof MERGE_FILES)[number][] = [];
   private head?: string;
-  private patchPath?: string;
-  private gitDir?: string;
+  private _gitDir?: string;
+
+  private get gitDir(): string {
+    return (this._gitDir ??= this.git(['rev-parse', '--absolute-git-dir']));
+  }
+
+  private get artifactsDir(): string {
+    return path.resolve(this.gitDir, ARTIFACTS_DIRECTORY);
+  }
+
+  private get patchPath(): string {
+    return path.resolve(this.artifactsDir, 'patch.diff');
+  }
 
   constructor(cwd: string, options: StageOptions = {}) {
     this.cwd = cwd;
@@ -72,7 +82,7 @@ export class Stage {
       )?.[1];
     } catch (error) {
       this.logger.log('⚠️ Git installation not found!');
-      throw error;
+      throw new Error('git installation not found');
     }
 
     if (!version || semver.lte(version, '2.13.0')) {
@@ -94,15 +104,50 @@ export class Stage {
       throw new Error('cwd is not a git repository root directory');
     }
 
+    // --absolute-git-dir resolves symlinks, --git-dir does not; if they
+    // differ, .git involves symlinks; walk the chain and reject if any
+    // target is inside the repo, because git stash --include-untracked
+    // would stash (and remove) it, breaking all subsequent operations
+    let gitDirPath = path.resolve(
+      this.cwd,
+      this.git(['rev-parse', '--git-dir']),
+    );
+
+    while (fs.lstatSync(gitDirPath).isSymbolicLink()) {
+      // readlink may return a relative path, so resolve against the
+      // symlink's parent directory to get an absolute path
+      const target = fs.readlinkSync(gitDirPath);
+      gitDirPath = path.resolve(path.dirname(gitDirPath), target);
+
+      if (!path.relative(this.cwd, gitDirPath).startsWith('..')) {
+        this.logger.log(
+          '⚠️ Git directory is a symlink pointing to a location within the repository!',
+        );
+        throw new Error(
+          'git directory is a symlink pointing to a location within the repository',
+        );
+      }
+    }
+
+    if (fs.existsSync(this.artifactsDir)) {
+      this.logger.log('⚠️ Found unexpected artifacts directory!');
+      this.logger.log(
+        'It must be left over from a previous failed run.  Run `exec-staged recover` to restore your repository.',
+      );
+      throw new Error('unexpected artifacts directory');
+    }
+
     if (this.indexOfBackupStash() !== -1) {
       this.logger.log('⚠️ Found unexpected backup stash!');
       this.logger.log(
-        'It must be left over from a previous failed run.  Remove it before proceeding.',
+        'It must be left over from a previous failed run.  Run `exec-staged recover` to restore your repository.',
       );
       throw new Error('unexpected backup stash');
     }
 
-    if (this.git(['log']).includes(STAGED_CHANGES_COMMIT_MESSAGE)) {
+    if (
+      this.git(['log', '--grep', STAGED_CHANGES_COMMIT_MESSAGE, '--format=%s'])
+    ) {
       this.logger.log('⚠️ Found unexpected temporary commit!');
       this.logger.log(
         'It must be left over from a previous failed run.  Remove it before proceeding.',
@@ -115,8 +160,6 @@ export class Stage {
     this.logger.log(stageLifecycleMessages.prepare);
 
     this.head = this.git(['rev-parse', 'HEAD']);
-    this.gitDir = this.git(['rev-parse', '--absolute-git-dir']);
-    this.patchPath = path.resolve(this.gitDir, 'patch.diff');
 
     this.git(['status', '--porcelain', '--no-renames'])
       .split('\n')
@@ -126,6 +169,8 @@ export class Stage {
     // if there are no files in index or working tree, do not attempt to stash
     if (Object.keys(this.status).length === 0) return;
 
+    fs.mkdirSync(this.artifactsDir);
+
     try {
       this.logger.debug('➡️ ➡️ Creating patch of unstaged changes...');
 
@@ -211,7 +256,11 @@ export class Stage {
               .filter(([, s]) => s.match(new RegExp(`^[${diff}]`)))
               .map(([f]) => f),
             glob,
-            { dot: true },
+            {
+              dot: true,
+              // match filenames in any directory when glob has no path separators
+              matchBase: !glob.includes('/'),
+            },
           );
 
           if (files.length === 0) {
@@ -269,16 +318,17 @@ export class Stage {
         '--unidiff-zero',
         '--whitespace=nowarn',
         '--3way',
-        this.patchPath!,
+        this.patchPath,
       ]);
 
       // unstaged deletions are not included in the patch and must be handled
       // separately because the patch cannot be applied if such files are
-      // modified by tasks
+      // modified by tasks; use force: true to handle cases where the file
+      // doesn't exist (e.g., unstaged renames)
       Object.entries(this.status)
         .filter(([, s]) => s.match(/^.D/))
         .map(([f]) => f)
-        .forEach((f) => fs.rmSync(path.resolve(this.cwd, f)));
+        .forEach((f) => fs.rmSync(path.resolve(this.cwd, f), { force: true }));
 
       // make sure all restored unstaged changes are kept out of the index
       this.git(['reset']);
@@ -287,14 +337,13 @@ export class Stage {
       this.git(['reset', '--soft', this.head!]);
 
       // clean up
-      fs.rmSync(this.patchPath!);
+      this.restoreMergeStatus();
+      fs.rmSync(this.artifactsDir, { recursive: true });
       this.git(['stash', 'drop', stash]);
     } catch (error) {
       this.logger.log('⚠️ Error restoring unstaged changes from stash!');
       throw error;
     }
-
-    this.restoreMergeStatus();
   }
 
   protected revert() {
@@ -325,6 +374,7 @@ export class Stage {
       this.git(['stash', 'apply', '--index', stash!]);
       this.git(['stash', 'drop', stash!]);
       this.restoreMergeStatus();
+      fs.rmSync(this.artifactsDir, { recursive: true });
     } catch (error) {
       this.logger.log('⚠️ Failed to restore state from backup stash!');
       throw error;
@@ -343,19 +393,20 @@ export class Stage {
 
   private backupMergeStatus() {
     for (const mergeFile of MERGE_FILES) {
-      const file = path.resolve(this.gitDir!, mergeFile);
-      if (fs.existsSync(file)) {
-        this.mergeStatus[mergeFile] = fs.readFileSync(file);
+      const src = path.resolve(this.gitDir, mergeFile);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, path.resolve(this.artifactsDir, mergeFile));
+        this.mergeStatus.push(mergeFile);
       }
     }
   }
 
   private restoreMergeStatus() {
-    for (const mergeFile of Object.keys(
-      this.mergeStatus,
-    ) as (keyof typeof this.mergeStatus)[]) {
-      const contents = this.mergeStatus[mergeFile]!;
-      fs.writeFileSync(path.resolve(this.gitDir!, mergeFile), contents);
+    for (const mergeFile of this.mergeStatus) {
+      fs.renameSync(
+        path.resolve(this.artifactsDir, mergeFile),
+        path.resolve(this.gitDir, mergeFile),
+      );
     }
   }
 
@@ -374,4 +425,41 @@ export class Stage {
 
     return `stash@{${index}}`;
   }
+
+  public recover() {
+    const stashIndex = this.indexOfBackupStash();
+    const stashFound = stashIndex !== -1;
+    const artifactsFound = fs.existsSync(this.artifactsDir);
+
+    if (!stashFound && !artifactsFound) {
+      this.logger.log('➡️ Nothing to recover.');
+      return;
+    }
+
+    if (stashFound) {
+      const stash = `stash@{${stashIndex}}`;
+
+      this.logger.log('➡️ Found backup stash, restoring...');
+
+      const head = this.git(['rev-parse', `${stash}^1`]);
+
+      this.git(['add', '-A']);
+      this.git(['reset', '--hard', head]);
+      this.git(['stash', 'apply', '--index', stash]);
+      this.git(['stash', 'drop', stash]);
+    }
+
+    if (artifactsFound) {
+      this.logger.log('➡️ Found artifacts directory, cleaning up...');
+
+      for (const mergeFile of MERGE_FILES) {
+        const src = path.resolve(this.artifactsDir, mergeFile);
+        if (fs.existsSync(src)) {
+          fs.renameSync(src, path.resolve(this.gitDir, mergeFile));
+        }
+      }
+
+      fs.rmSync(this.artifactsDir, { recursive: true });
+    }
+  }
 }