git-greener

The grass is always greener on the other side -- bring your commits with you.

Replay your git commit history into a new repository with preserved dates. Your GitHub contribution graph comes with you.

No source code is transferred -- only commit metadata (dates and subject lines). Safe for proprietary codebases.

The 5-Minute Migration

On your old machine (work laptop, etc.)

No install required. Run from the root of the repo you want to export:

# Basic: all commits on current branch
git log --pretty=format:"%H | %aI | %ae | %s" > commits.txt

Optional refinements (paste one of these instead if you need them):

# Only your commits (replace with your work email)
git log --author="[email protected]" --pretty=format:"%H | %aI | %ae | %s" > commits.txt

# Only commits since a date (ISO 8601)
git log --since="2023-01-01" --pretty=format:"%H | %aI | %ae | %s" > commits.txt

# Specific branch (e.g. main)
git log main --pretty=format:"%H | %aI | %ae | %s" > commits.txt

# Combine: your commits on main from the last two years
git log main --author="[email protected]" --since="2023-01-01" --pretty=format:"%H | %aI | %ae | %s" > commits.txt

Transfer commits.txt to your personal machine (email, USB, AirDrop, paste into a Gist, scp, etc.).

On your personal machine

Do this in an empty or dedicated repo (e.g. a new GitHub repo you created for the migration):

# 1. Always preview first (dry-run is the default)
npx git-greener replay commits.txt

# 2. If the summary looks correct, run for real
npx git-greener replay commits.txt --execute

# 3. Skip the confirmation prompt (e.g. in scripts)
npx git-greener replay commits.txt --execute --yes

Then push to GitHub (git push -u origin main or your default branch). Your contribution graph will reflect the replayed commits.

Use Cases

• Leaving a job -- Your work GitHub contributions disappear when you lose access. Bring them with you.
• Consolidating GitHub profiles -- Merge multiple accounts into one unified contribution history.
• Freelancers and contractors -- Unify contributions across client organizations.
• Students -- Transitioning from a university GitHub to your personal account.
• Migrating between platforms -- Moving from GitLab, Bitbucket, or self-hosted Git to GitHub.
• Lost or deleted repos -- Recreate your contribution history from a local clone.
• Open-sourcing internal projects -- Preserve contributor credit when making a private repo public.

Installation

# Run directly with npx (no install needed)
npx git-greener <command>

# Or install globally
npm install -g git-greener

Requires Node.js 20 or later.

CLI Reference

git-greener extract

Extract commit history from one or more repositories. Use this when you have git-greener installed on the machine where the repos live (e.g. your work laptop).

git-greener extract <repos...> [options]

| Option | Description | | -------------------------- | ---------------------------------------------------------------- | | -a, --author <email> | Only include commits by this author (matches exact email) | | -s, --since <date> | Only commits on or after this date (ISO 8601, e.g. 2024-01-01) | | -u, --until <date> | Only commits on or before this date | | -o, --out <file> | Write output to this file (default: stdout) | | -b, --branches <pattern> | Branch name or glob to extract from (default: current HEAD) |

Examples:

# All commits from current branch → file
git-greener extract ~/my-project --out commits.txt

# Only your commits (use your work email)
git-greener extract ~/my-project --author [email protected] --out commits.txt

# Time window: last calendar year
git-greener extract ~/my-project --since 2024-01-01 --until 2024-12-31 --out commits.txt

# From a specific branch (e.g. main or develop)
git-greener extract ~/my-project --branches main --out commits.txt

# Combine: your commits on main from 2024
git-greener extract ~/my-project -a [email protected] -b main -s 2024-01-01 -u 2024-12-31 -o commits.txt

# Multiple repos into one file (one commits list for one “greener” repo)
git-greener extract ~/project-a ~/project-b ~/project-c --out commits.txt

# Pipe to stdout, then redirect yourself
git-greener extract ~/my-project --author [email protected] > my-commits.txt

Doing it properly: Prefer --author so you only export your own commits. Use --since / --until to match the period you actually worked (e.g. employment dates). Use --out so you have a single file to move to your other machine.

git-greener replay

Replay commit history from a commits file into the current repository. Run this from the root of the target repo (e.g. your new personal repo).

git-greener replay <file> [options]

| Option | Description | | ---------------------- | -------------------------------------------------------------------------- | | --execute | Apply changes (without this, replay is dry-run only) | | --redact | Replace every message with work commit 1, work commit 2, … for privacy | | --batch | Use git fast-import; use for very large histories (thousands of commits) | | -y, --yes | Do not prompt for confirmation (useful in scripts) | | -a, --author <email> | Only replay commits whose author email matches (e.g. filter to your email) | | -s, --since <date> | Only replay commits on or after this date (ISO 8601) | | -u, --until <date> | Only replay commits on or before this date |

Examples:

# Always start with a preview (dry-run). No files are changed.
git-greener replay commits.txt

# Run for real; you'll get a summary and a confirmation prompt
git-greener replay commits.txt --execute

# Non-interactive (e.g. in a script or when you're sure)
git-greener replay commits.txt --execute --yes

# Privacy: strip real commit messages (e.g. for employer policy)
git-greener replay commits.txt --execute --redact

# Large history: use batch mode to avoid thousands of separate git calls
git-greener replay commits.txt --execute --batch

# Replay only a subset: your email and a date range
git-greener replay commits.txt --execute --author [email protected] --since 2024-01-01 --until 2024-03-31

# Preview a subset before executing
git-greener replay commits.txt --author [email protected] --since 2024-01-01

Doing it properly: (1) Run replay without --execute first and check the summary. (2) Use a clean repo (no uncommitted changes). (3) Use --author if the commits file has multiple authors and you only want yours. (4) Use --redact if you need to avoid exposing original message content. (5) Use --batch only when you have a very large number of commits and dry-run or normal replay is slow.

How It Works

1. Extract reads git log and outputs a pipe-delimited text file with commit metadata (SHA, date, author email, subject line).

2. Replay reads that file and creates empty commits (git commit --allow-empty) with the original author and committer dates preserved.

3. GitHub's contribution graph uses the author date from commit metadata. By setting GIT_AUTHOR_DATE and GIT_COMMITTER_DATE, each replayed commit appears on the correct day in your contribution graph.

4. No files or source code are included -- commits are empty. Only the metadata (dates and optionally subject lines) transfer.

Commits File Format

Each line is one commit, pipe-delimited:

<sha> | <date> | <author_email> | <subject>

• sha — Full commit hash (e.g. 40-char SHA-1).
• date — ISO 8601 with timezone (e.g. 2024-03-15T10:30:00-06:00). This is the author date used for the contribution graph.
• author_email — Email of the commit author (used for --author filtering on replay).
• subject — First line of the commit message (omitted if you use --redact on replay).

Example:

a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 | 2024-03-15T10:30:00-06:00 | [email protected] | Add authentication module

A 3-field format (sha | date | subject) is also supported for backward compatibility. When using the manual git log one-liner, the 4-field format is preferred so --author filtering works on replay.

Safety Features

• Dry-run by default -- You must explicitly pass --execute to make changes.
• Interactive confirmation -- Shows a summary and asks for confirmation before executing.
• Automatic backup -- Creates a backup-before-greener-* branch before any replay.
• Dirty repo detection -- Refuses to run if you have uncommitted changes.
• No shell injection -- All git operations use execFile, never shell execution.
• Commit bodies stripped -- Only subject lines are extracted, never full commit bodies.
• Redact mode -- --redact replaces all messages with generic text for extra privacy.

Best Practices

• Dry-run first — Always run replay without --execute and check the commit count and date range before applying.
• Export only what you need — On the source machine, filter by --author and optionally --since / --until so the commits file contains only your commits in the desired window.
• Use a dedicated repo — Replay into a new or empty repo (e.g. github.com/you/greener-history), not into an existing project with real code.
• Clean working tree — Replay refuses to run with uncommitted changes; commit or stash first.
• Redact when unsure — If employer or client policy is unclear, use --redact so only dates (and optionally author) are preserved, not message text.
• One commits file per “greener” repo — You can merge multiple source repos into one file with extract repo1 repo2 ... --out commits.txt, then replay once into a single target repo.

Important Disclaimer

Check your employer's policies before using this tool. Many employment agreements restrict use of company intellectual property. git-greener only preserves commit metadata (dates and optionally subject lines) -- no source code is transferred. Use --redact if you want to strip commit messages entirely. This tool is provided as-is and the authors assume no liability for its use.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

MIT