anil.recoil.org
A monorepo management tool for the agentic ages
1(** Git worktree lifecycle management for unpac.
2
3 Manages creation, cleanup, and paths of worktrees within the unpac
4 directory structure. All branch operations happen in isolated worktrees.
5
6 {2 Directory Structure}
7
8 An unpac project has this layout:
9 {v
10 my-project/
11 ├── git/ # Bare repository
12 ├── main/ # Worktree → main branch
13 ├── project/
14 │ └── myapp/ # Worktree → project/myapp
15 ├── opam/
16 │ ├── upstream/
17 │ │ └── pkg/ # Worktree → opam/upstream/pkg
18 │ ├── vendor/
19 │ │ └── pkg/ # Worktree → opam/vendor/pkg
20 │ └── patches/
21 │ └── pkg/ # Worktree → opam/patches/pkg
22 └── git-repos/
23 ├── upstream/
24 │ └── repo/ # Worktree → git/upstream/repo
25 ├── vendor/
26 │ └── repo/ # Worktree → git/vendor/repo
27 └── patches/
28 └── repo/ # Worktree → git/patches/repo
29 v} *)
30
31(** {1 Types} *)
32
33type root = Eio.Fs.dir_ty Eio.Path.t
34(** The unpac project root directory (contains git/, main/, etc.) *)
35
36type kind =
37 | Main
38 | Project of string
39 | Opam_upstream of string
40 | Opam_vendor of string
41 | Opam_patches of string
42 | Git_upstream of string
43 | Git_vendor of string
44 | Git_patches of string
45(** Worktree kinds with their associated names.
46 Opam_* variants are for opam package vendoring.
47 Git_* variants are for direct git repository vendoring. *)
48
49(** {1 Path and Branch Helpers} *)
50
51val git_dir : root -> Eio.Fs.dir_ty Eio.Path.t
52(** [git_dir root] returns the path to the bare git repository. *)
53
54val path : root -> kind -> Eio.Fs.dir_ty Eio.Path.t
55(** [path root kind] returns the filesystem path for the worktree. *)
56
57val branch : kind -> string
58(** [branch kind] returns the git branch name for the worktree kind. *)
59
60(** {1 Queries} *)
61
62val exists : root -> kind -> bool
63(** [exists root kind] checks if the worktree directory exists. *)
64
65val branch_exists : proc_mgr:Git.proc_mgr -> root -> kind -> bool
66(** [branch_exists ~proc_mgr root kind] checks if the branch exists in git. *)
67
68(** {1 Operations} *)
69
70val ensure : proc_mgr:Git.proc_mgr -> root -> kind -> unit
71(** [ensure ~proc_mgr root kind] creates the worktree if it doesn't exist.
72 The branch must already exist. *)
73
74val ensure_orphan : proc_mgr:Git.proc_mgr -> root -> kind -> unit
75(** [ensure_orphan ~proc_mgr root kind] creates an orphan worktree.
76 Creates a new orphan branch. *)
77
78val ensure_detached : proc_mgr:Git.proc_mgr -> root -> kind -> commit:string -> unit
79(** [ensure_detached ~proc_mgr root kind ~commit] creates a detached worktree
80 at the given commit. Does not create a branch. *)
81
82val remove : proc_mgr:Git.proc_mgr -> root -> kind -> unit
83(** [remove ~proc_mgr root kind] removes the worktree (keeps the branch). *)
84
85val remove_force : proc_mgr:Git.proc_mgr -> root -> kind -> unit
86(** [remove_force ~proc_mgr root kind] forcibly removes the worktree. *)
87
88val with_temp : proc_mgr:Git.proc_mgr -> root -> kind -> (Eio.Fs.dir_ty Eio.Path.t -> 'a) -> 'a
89(** [with_temp ~proc_mgr root kind f] creates the worktree, runs [f] with
90 the worktree path, then removes the worktree. *)
91
92val with_temp_orphan : proc_mgr:Git.proc_mgr -> root -> kind -> (Eio.Fs.dir_ty Eio.Path.t -> 'a) -> 'a
93(** [with_temp_orphan ~proc_mgr root kind f] creates an orphan worktree,
94 runs [f], then removes the worktree. *)
95
96(** {1 Listing} *)
97
98val list_worktrees : proc_mgr:Git.proc_mgr -> root -> string list
99(** [list_worktrees ~proc_mgr root] returns paths of all worktrees. *)
100
101val list_projects : proc_mgr:Git.proc_mgr -> root -> string list
102(** [list_projects ~proc_mgr root] returns names of all project branches. *)
103
104val list_opam_packages : proc_mgr:Git.proc_mgr -> root -> string list
105(** [list_opam_packages ~proc_mgr root] returns names of all vendored opam packages
106 (packages with opam/patches/* branches). *)
107
108val list_git_repos : proc_mgr:Git.proc_mgr -> root -> string list
109(** [list_git_repos ~proc_mgr root] returns names of all vendored git repositories
110 (repos with git/patches/* branches). *)