anil.recoil.org
A monorepo management tool for the agentic ages
1# Unpac CLI Workflow
2
3## Overview
4
5Unpac is a vendoring tool that lets you maintain local patches to dependencies while tracking upstream changes. This document describes the ideal CLI workflow.
6
7## Quick Start
8
9```bash
10# Initialize a new unpac workspace
11unpac init myworkspace
12cd myworkspace
13
14# Configure an opam repository
15unpac opam repo add opam-repository /path/to/opam-repository
16
17# Create a project
18unpac project new myapp
19
20# Add a dependency (looks up dev-repo in opam repository)
21unpac opam add cmdliner
22
23# Edit the vendored package (opens patches worktree)
24unpac opam edit cmdliner
25# ... make changes, e.g., port to dune ...
26cd opam/patches/cmdliner
27git add -A && git commit -m "Port cmdliner to dune"
28cd ../../..
29
30# Add the patched package to your project
31unpac opam merge cmdliner myapp
32
33# Build your project
34cd project/myapp
35dune build
36```
37
38## Commands
39
40### Initialization
41
42#### `unpac init <path>`
43
44Initialize a new unpac workspace at the given path.
45
46```bash
47unpac init myworkspace
48```
49
50Creates:
51- `git/` - bare git repository (shared object store)
52- `main/` - metadata branch with `unpac.toml`
53
54### Project Management
55
56#### `unpac project new <name>`
57
58Create a new project branch.
59
60```bash
61unpac project new myapp
62```
63
64Creates an orphan branch `project/<name>` with:
65- `dune-project` with dune lang 3.20
66- `dune` with `(vendored_dirs vendor)`
67- `vendor/opam/` directory structure
68
69#### `unpac project list`
70
71List all projects in the workspace.
72
73```bash
74unpac project list
75```
76
77### Opam Repository Management
78
79#### `unpac opam repo add <name> <path-or-url>`
80
81Add an opam repository for package lookups.
82
83```bash
84# Local repository
85unpac opam repo add opam-repository /workspace/opam/opam-repository
86
87# Remote repository (planned)
88unpac opam repo add opam-repository https://github.com/ocaml/opam-repository
89```
90
91#### `unpac opam repo list`
92
93List configured opam repositories.
94
95```bash
96unpac opam repo list
97```
98
99#### `unpac opam repo remove <name>`
100
101Remove an opam repository.
102
103```bash
104unpac opam repo remove opam-repository
105```
106
107### Package Vendoring
108
109#### `unpac opam add <package-or-url> [--name <name>] [--version <version>]`
110
111Vendor a package. Can specify either:
112- A package name (looks up dev-repo in configured repositories)
113- A git URL directly
114
115```bash
116# By package name (recommended)
117unpac opam add cmdliner
118unpac opam add cmdliner --version 1.3.0
119
120# By URL (for packages not in a repository)
121unpac opam add https://github.com/dbuenzli/cmdliner.git --name cmdliner
122```
123
124This creates three branches:
125- `opam/upstream/<pkg>` - pristine upstream code
126- `opam/vendor/<pkg>` - code with `vendor/opam/<pkg>/` path prefix
127- `opam/patches/<pkg>` - your local modifications (initially same as vendor)
128
129#### `unpac opam list`
130
131List all vendored packages.
132
133```bash
134unpac opam list
135```
136
137#### `unpac opam edit <package>`
138
139Open the patches worktree for editing a package.
140
141```bash
142unpac opam edit cmdliner
143```
144
145Creates/checks out `opam/patches/cmdliner/` worktree. Make your changes there, then commit:
146
147```bash
148cd opam/patches/cmdliner
149# ... edit files ...
150git add -A
151git commit -m "Port to dune build system"
152```
153
154#### `unpac opam done <package>`
155
156Close the patches worktree (cleanup after editing).
157
158```bash
159unpac opam done cmdliner
160```
161
162#### `unpac opam update <package>`
163
164Update a package from upstream.
165
166```bash
167unpac opam update cmdliner
168```
169
170This:
1711. Fetches latest from upstream
1722. Updates `opam/upstream/<pkg>` and `opam/vendor/<pkg>`
1733. Prints instructions for rebasing patches if needed
174
175#### `unpac opam rebase <package>`
176
177Rebase your patches onto the updated vendor branch.
178
179```bash
180unpac opam rebase cmdliner
181```
182
183Opens the patches worktree for conflict resolution if needed.
184
185#### `unpac opam merge <package> <project>`
186
187Merge a vendored package into a project.
188
189```bash
190unpac opam merge cmdliner myapp
191```
192
193Merges `opam/patches/<pkg>` into `project/<name>`, placing files under `vendor/opam/<pkg>/`.
194
195#### `unpac opam remove <package>`
196
197Remove a vendored package.
198
199```bash
200unpac opam remove cmdliner
201```
202
203### Package Information
204
205#### `unpac opam info <package>`
206
207Show information about a vendored package.
208
209```bash
210unpac opam info cmdliner
211```
212
213Shows:
214- Upstream URL
215- Current upstream SHA
216- Current patches SHA
217- Number of local commits
218- Projects using this package
219
220#### `unpac opam diff <package>`
221
222Show the diff between vendor and patches (your local changes).
223
224```bash
225unpac opam diff cmdliner
226```
227
228## Workflow Examples
229
230### Porting a Package to Dune
231
232```bash
233# Setup
234unpac init myworkspace && cd myworkspace
235unpac opam repo add opam-repository /workspace/opam/opam-repository
236unpac project new myapp
237
238# Vendor and patch
239unpac opam add cmdliner
240unpac opam edit cmdliner
241
242cd opam/patches/cmdliner
243# Add dune files, remove _tags, etc.
244git add -A
245git commit -m "Port cmdliner to dune"
246cd ../../..
247
248unpac opam done cmdliner
249
250# Use in project
251unpac opam merge cmdliner myapp
252cd project/myapp
253dune build
254```
255
256### Updating a Patched Package
257
258```bash
259# Update from upstream
260unpac opam update cmdliner
261
262# Rebase your patches
263unpac opam rebase cmdliner
264
265# If conflicts, resolve them:
266cd opam/patches/cmdliner
267# ... resolve conflicts ...
268git add -A
269git rebase --continue
270cd ../../..
271
272unpac opam done cmdliner
273
274# Re-merge into project
275unpac opam merge cmdliner myapp
276```
277
278### Adding Multiple Dependencies
279
280```bash
281unpac opam add fmt
282unpac opam add logs
283unpac opam add cmdliner
284
285# Merge all into project
286unpac opam merge fmt myapp
287unpac opam merge logs myapp
288unpac opam merge cmdliner myapp
289```
290
291## Directory Structure
292
293After setup, your workspace looks like:
294
295```
296myworkspace/
297├── git/ # Bare git repo (shared objects)
298├── main/ # Metadata worktree
299│ └── unpac.toml # Configuration
300├── project/
301│ └── myapp/ # Project worktree
302│ ├── dune-project
303│ ├── dune
304│ └── vendor/
305│ └── opam/
306│ ├── cmdliner/ # Merged vendor code
307│ └── fmt/
308└── opam/ # Package worktrees (on-demand)
309 └── patches/
310 └── cmdliner/ # When editing
311```
312
313## Configuration (unpac.toml)
314
315```toml
316[opam]
317repositories = [
318 { name = "opam-repository", path = "/workspace/opam/opam-repository" }
319]
320# compiler = "5.4.0" # Optional: pin compiler version
321
322[projects]
323myapp = {}
324```