hero-migration

Automatically clean migration-generated file changes while preserving your own changes. Zero configuration required!

Installation

Local Installation (Recommended)

npm install --save-dev hero-migration
# or
yarn add -D hero-migration

Global Installation (Optional)

npm install -g hero-migration
# or
yarn global add hero-migration

That's it! The package will automatically:

• ✅ Install pre-commit hook
• ✅ Create .git-exclude-list.example template
• ✅ Set up everything you need

Note: After local installation, use npx hero-migration or add ./node_modules/.bin to your PATH.

Quick Start

1. Copy the exclude list template:

   cp .git-exclude-list.example .git-exclude-list

2. Edit .git-exclude-list and add files you want to exclude (one per line):

   package.json
   babel.config.json
   .gitlab-ci.yml

3. Run migration and save snapshot:

   # Run migration (automatically saves snapshot and adds files to exclude list)
   hero-migration
   # or with npx (if installed locally)
   npx hero-migration
      
   # Or manually save snapshot after migration
   hero-migration save

4. Commit normally - changes will be auto-cleaned! 🎉

Commands

hero-migration (default)

Run momo-migration, automatically save snapshot, and add changed files to .git-exclude-list.

Usage:

hero-migration
# or with npx (if installed locally)
npx hero-migration

hero-migration save

Save snapshot of migration files. Run this immediately after running your migration tool.

hero-migration clean

Manually clean migration changes while preserving your changes.

hero-migration status

Show which files have user changes vs migration-only changes.

Legacy commands (still available):

• git-migration-save → hero-migration save
• git-migration-clean → hero-migration clean
• git-migration-status → hero-migration status

How It Works

1. After migration: Run git-migration-save to snapshot migration-generated files
2. Make your changes: Edit files normally
3. On commit: Pre-commit hook automatically:
   • Discards files that only have migration changes
   • Cleans migration changes from files that have your changes
   • Preserves your changes automatically

Example Workflow

# 1. Run migration (automatically saves snapshot and adds files to exclude list)
hero-migration
# This will:
#   - Run momo-migration
#   - Detect changed files
#   - Add them to .git-exclude-list
#   - Save migration snapshot

# 2. Make your changes
vim package.json  # Add your dependencies

# 3. Commit - hook automatically handles cleanup!
git add .
git commit -m "Add my feature"
# ✅ Only your changes are committed!

Alternative workflow (manual steps):

# 1. Run your migration tool
momo-migration

# 2. Save snapshot manually
hero-migration save

# 3. Make your changes and commit

Configuration

.git-exclude-list

List of files to exclude from commits (one per line). Comments start with #.

Example:

# Migration-generated files
package.json
babel.config.json
.gitlab-ci.yml

# Build artifacts
sourcemap/
coverage/

.git-exclude-list.local

Personal exclude list (not tracked in git). Same format as .git-exclude-list.

Features

• 🚀 Zero configuration - Works out of the box
• 🧹 Automatic cleanup - Pre-commit hook handles everything
• 💾 Smart detection - Only cleans migration changes, preserves yours
• 🔄 Works with any migration tool - Not tied to specific tools
• 📦 Lightweight - No heavy dependencies

Troubleshooting

Hook not running?

# Make sure hook is executable
chmod +x .git/hooks/pre-commit

# Test hook manually
.git/hooks/pre-commit

Need to commit excluded file anyway?

# Temporarily remove from exclude list, commit, then add back
# Or use --no-verify to skip hooks (not recommended)
git commit --no-verify

See what files are staged?

git status
git diff --cached --name-only

License

MIT