A tool to help managing forked repos with their own history
me.webbeef.org
1# forkme
2
3A tool for managing forks of large projects using a patch-based approach.
4
5## The Problem
6
7When maintaining a fork of a large project, there are two common approaches:
8
9- **Rebase**: Rewrite your changes on top of upstream. Clean history, but requires force-pushing.
10- **Merge**: Merge upstream into your branch. Preserves history, but creates merge commits that may not build cleanly, making bisecting difficult.
11
12## The Solution
13
14**forkme** takes a different approach: keep your changes as a set of patches, organized by file path. This gives you:
15
16- Clean history of your own changes
17- Simple conflict resolution during upstream updates
18- No force-pushes required
19
20## Project Structure
21
22A forkme-managed project looks like this:
23
24```
25my-fork/
26├── forkme.toml # Configuration (upstream URL, branch)
27├── patches/ # Your patches, organized by file path
28│ ├── src/
29│ │ └── main.rs.patch
30│ └── Cargo.toml.patch
31└── source/ # Upstream repo with your changes (in .gitignore)
32```
33
34Only `forkme.toml` and `patches/` are committed to your repository.
35
36## Installation
37
38```bash
39cargo install --path .
40```
41
42## Usage
43
44### Initialize a new project
45
46```bash
47forkme init --url https://github.com/user/repo --branch main
48```
49
50This will:
51- Create `forkme.toml` with upstream configuration
52- Clone the upstream repo into `source/`
53- Create a `forkme` branch for your work
54- Set up `.gitignore` to exclude `source/`
55
56### Make changes
57
58Work in the `source/` directory on the `forkme` branch:
59
60```bash
61cd source
62# edit files, make commits
63git commit -m "My changes"
64```
65
66### Sync changes to patches
67
68```bash
69forkme sync
70```
71
72This updates patch files in `patches/` based on your changes.
73
74### Update from upstream
75
76```bash
77forkme update
78```
79
80This fetches upstream and rebases your `forkme` branch. If there are conflicts, resolve them with standard git commands, then run `forkme sync` to regenerate patches.
81
82### Apply patches (after fresh clone)
83
84```bash
85forkme init # Uses existing forkme.toml
86```
87
88Or to reset and reapply:
89
90```bash
91forkme apply
92```
93
94### Check status
95
96```bash
97forkme status # Project overview
98forkme stats # Patch statistics (added/modified/deleted)
99```
100
101## Commands
102
103| Command | Description |
104|---------|-------------|
105| `init --url <url> [--branch <branch>]` | Initialize project with upstream repo |
106| `apply` | Reset to upstream and reapply all patches |
107| `sync` | Generate patches from current changes |
108| `update` | Fetch upstream and rebase |
109| `status` | Show project status |
110| `stats` | Show patch statistics |
111
112## License
113
114AGPL 3.0