My aggregated monorepo of OCaml code, automaintained
Update CLAUDE.md usage tips
+74
-30
+74
-30
CLAUDE.md
+74
-30
CLAUDE.md
···
3
3
This is a monorepo managed by `monopam`. Each subdirectory is a git subtree
4
4
from a separate upstream repository.
5
5
6
-
## Making Changes
6
+
> **Note:** Check `CLAUDE.local.md` (if it exists) for additional local
7
+
> configuration or preferences specific to this workspace.
7
8
8
-
1. Edit code in any subdirectory as normal
9
-
2. Build and test: `opam exec -- dune build` and `opam exec -- dune test`
10
-
3. Commit your changes to this monorepo with git
9
+
## Quick Reference
11
10
12
-
## Exporting Changes to Upstream
11
+
| Task | Command |
12
+
|------|---------|
13
+
| Check status | `monopam status` |
14
+
| Sync all repos | `monopam sync` |
15
+
| Sync and push upstream | `monopam sync --remote` |
16
+
| Sync one repo | `monopam sync <repo-name>` |
17
+
| Build | `opam exec -- dune build` |
18
+
| Test | `opam exec -- dune test` |
13
19
14
-
After committing changes here, they must be exported to the individual
15
-
repositories before they can be pushed upstream:
20
+
## Daily Workflow
16
21
17
-
```
18
-
monopam push
19
-
```
22
+
```bash
23
+
# 1. Check what needs syncing
24
+
monopam status
20
25
21
-
This extracts your commits into the individual checkouts in `../src/`.
22
-
You then review and push each one manually:
26
+
# 2. Sync your monorepo with all upstreams
27
+
monopam sync
28
+
29
+
# 3. Make your changes, build and test
30
+
opam exec -- dune build && opam exec -- dune test
31
+
32
+
# 4. Commit your changes
33
+
git add -A && git commit -m "Description of changes"
23
34
24
-
```
25
-
cd ../src/<repo-name>
26
-
git log --oneline -5 # review the changes
27
-
git push origin main # push to upstream
35
+
# 5. Sync and push to upstream remotes
36
+
monopam sync --remote
28
37
```
29
38
30
-
## Pulling Updates from Upstream
39
+
## Understanding Status Output
31
40
32
-
To fetch the latest changes from all upstream repositories:
41
+
Run `monopam status` to see the sync state:
33
42
34
-
```
35
-
monopam pull
36
-
```
43
+
- `local:=` - Monorepo and checkout in sync
44
+
- `local:+N` - Monorepo is N commits ahead (run `monopam sync`)
45
+
- `local:-N` - Checkout is N commits ahead (run `monopam sync`)
46
+
- `local:sync` - Trees differ, needs sync (run `monopam sync`)
47
+
- `remote:=` - Checkout and upstream in sync
48
+
- `remote:+N` - You have N commits to push (run `monopam sync --remote`)
49
+
- `remote:-N` - Upstream has N commits to pull (run `monopam sync`)
37
50
38
-
This updates both the checkouts and merges changes into this monorepo.
51
+
## Making Changes
52
+
53
+
1. **Edit code** in any subdirectory as normal
54
+
2. **Build and test**: `opam exec -- dune build && opam exec -- dune test`
55
+
3. **Commit** your changes: `git add -A && git commit`
56
+
4. **Sync**: `monopam sync --remote` to push to upstreams
39
57
40
58
## Important Notes
41
59
42
-
- **Always commit before push**: `monopam push` only exports committed changes
43
-
- **Check status first**: Run `monopam status` to see which repos have changes
60
+
- **Always commit before sync**: `monopam sync` only exports committed changes
61
+
- **Check status first**: Run `monopam status` to see what needs attention
44
62
- **One repo per directory**: Each subdirectory maps to exactly one git remote
45
-
- **Shared repos**: Multiple opam packages may live in the same subdirectory
46
-
if they share an upstream repository
47
63
48
64
## Troubleshooting
49
65
50
-
If `monopam push` fails with "dirty state", you have uncommitted changes.
51
-
Commit or stash them first.
66
+
### "Dirty packages" Error
67
+
Commit your changes first:
68
+
```bash
69
+
git status && git add -A && git commit -m "Your message"
70
+
```
52
71
53
-
If merge conflicts occur during `monopam pull`, resolve them in this monorepo,
54
-
commit, then the next pull will succeed.
72
+
### "local:sync" in Status
73
+
Trees differ but need syncing:
74
+
```bash
75
+
monopam sync
76
+
```
77
+
78
+
### Merge Conflicts
79
+
Resolve conflicts, commit, then sync:
80
+
```bash
81
+
git add -A && git commit -m "Resolve merge conflicts"
82
+
monopam sync
83
+
```
84
+
85
+
### Push Fails
86
+
Check credentials:
87
+
```bash
88
+
cd ../src/<repo-name>
89
+
git push origin main # For better error messages
90
+
```
91
+
92
+
## Getting Help
93
+
94
+
```bash
95
+
monopam --help # Main help
96
+
monopam sync --help # Sync command help
97
+
monopam status --help # Status command help
98
+
```