forkme#

A tool for managing forks of large projects using a patch-based approach.

The Problem#

When maintaining a fork of a large project, there are two common approaches:

• Rebase: Rewrite your changes on top of upstream. Clean history, but requires force-pushing.
• Merge: Merge upstream into your branch. Preserves history, but creates merge commits that may not build cleanly, making bisecting difficult.

The Solution#

forkme takes a different approach: keep your changes as a set of patches, organized by file path. This gives you:

• Clean history of your own changes
• Simple conflict resolution during upstream updates
• No force-pushes required

Project Structure#

A forkme-managed project looks like this:

my-fork/
├── forkme.toml     # Configuration (upstream URL, branch)
├── patches/        # Your patches, organized by file path
│   ├── src/
│   │   └── main.rs.patch
│   └── Cargo.toml.patch
└── source/         # Upstream repo with your changes (in .gitignore)

Only forkme.toml and patches/ are committed to your repository.

Installation#

cargo install --path .

Usage#

Initialize a new project#

forkme init --url https://github.com/user/repo --branch main

This will:

• Create forkme.toml with upstream configuration
• Clone the upstream repo into source/
• Create a forkme branch for your work
• Set up .gitignore to exclude source/

Make changes#

Work in the source/ directory on the forkme branch:

cd source
# edit files, make commits
git commit -m "My changes"

Sync changes to patches#

forkme sync

This updates patch files in patches/ based on your changes.

Update from upstream#

forkme update

This fetches upstream and rebases your forkme branch. If there are conflicts, resolve them with standard git commands, then run forkme sync to regenerate patches.

Apply patches (after fresh clone)#

forkme init  # Uses existing forkme.toml

Or to reset and reapply:

forkme apply

Check status#

forkme status  # Project overview
forkme stats   # Patch statistics (added/modified/deleted)

Commands#

License#

AGPL 3.0