Shipdiff

Know what changed. Ship only what matters.

Shipdiff is a tiny, local-first Git CLI that prepares the files changed since your last completed handoff.

It is designed for workflows where development happens in Git, but delivery still happens through FTP/FileZilla, SFTP, shared drives, hosting file managers, vendors, clients, or other manual processes.

Git commits
    |
    v
 shipdiff
    |
    +-- added
    +-- modified
    +-- renamed
    +-- deleted
    |
    v
_shipdiff/
    |
    v
FTP / SFTP / Drive / Client / Vendor

Why?

Git already knows what changed. The annoying part in a manual handoff is remembering which files need to be uploaded, replaced, or removed.

Shipdiff turns that Git history into a ready-to-deliver folder while preserving the original directory structure.

Install

npm install -g shipdiff

Requirements:

• Node.js 18+
• Git
• a Git repository

Shipdiff has no runtime dependencies.

Quick start

Initialize Shipdiff inside an existing Git repository:

shipdiff init

Your current commit becomes R00, the baseline.

Work and commit normally:

git add .
git commit -m "Update homepage"

Prepare the next handoff:

shipdiff

Example output:

Shipdiff R01

ADDED
+ assets/images/new-banner.webp

MODIFIED
~ index.html
~ assets/css/home.css

DELETED
- assets/images/old-banner.webp

Output: _shipdiff/

After delivery:
shipdiff done

The generated directory preserves your project structure:

_shipdiff/
├── index.html
├── assets/
│   ├── css/
│   │   └── home.css
│   └── images/
│       └── new-banner.webp
└── REVISION.txt

Upload or deliver the files however your workflow requires. Shipdiff never uploads anything itself.

After the files have actually been delivered:

shipdiff done

That commit becomes the baseline for the next revision.

Commands

| Command | What it does | | --- | --- | | shipdiff init | Initialize tracking and use the current commit as R00 | | shipdiff | Generate the next handoff from changes since the last completed revision | | shipdiff status | Show the last completed revision and pending changes | | shipdiff done | Mark the current generated revision as delivered | | shipdiff log | Show history of all completed revisions (latest first) | | shipdiff log --summary | Show cumulative net unique files changed across all revisions | | shipdiff reset | Reset tracking and use the current commit as a new baseline | | shipdiff --help | Show CLI help | | shipdiff --version | Show the installed version |

What gets detected?

Shipdiff uses Git to detect:

• added files
• modified files
• renamed files
• deleted files

Replacing an image while keeping the same filename is still detected as a modification.

MODIFIED
~ assets/images/hero.jpg

Deleted files cannot be copied into _shipdiff/, so Shipdiff lists them in the terminal and in REVISION.txt so you know what must be removed from the destination.

Clean working tree

Shipdiff requires changes to be committed before generating a handoff.

This is intentional: the Git commit, generated handoff, and delivered source should all describe the same version.

Local state

Shipdiff creates two local artifacts:

.shipdiff-state.json
_shipdiff/

shipdiff init adds them to .gitignore.

The state file remembers the last completed revision and commit. _shipdiff/ is temporary output and is recreated when a new handoff is generated.

Safety

Shipdiff is deliberately local-first and narrow in scope.

It does not:

• upload files
• connect to FTP or SFTP
• access external APIs
• push to Git remotes
• modify Git history
• run deployment commands
• delete application source files

It reads Git metadata, copies changed files into _shipdiff/, and maintains its local state file.

Typical use cases

• manual FTP / FileZilla deployments
• frontend-to-backend handoffs
• agency and client revision workflows
• legacy deployment environments
• shared-drive deliveries
• vendor handoffs

Philosophy

Shipdiff does not replace Git.

It bridges the gap between Git-based development and manual delivery.

Git knows what changed. Shipdiff makes it shippable.

License

MIT