forked from
anil.recoil.org/monopam
Monorepo management for opam overlays
1(** Import packages from git repositories.
2
3 Handles the core logic for importing packages from git repositories into the
4 current project. *)
5
6(** {1 Types} *)
7
8type source =
9 | Git_url of {
10 url : string;
11 branch : string option;
12 ref_ : string option;
13 path : string option;
14 (** If [Some p], [url] is treated as a monorepo and only the
15 subdirectory [p] is materialized as a local subtree. See
16 {!Sources_registry.entry.path}. *)
17 }
18
19type result = {
20 name : string; (** Directory name of the imported subtree *)
21 commit : string; (** Full commit SHA that was imported *)
22 added : bool; (** true if newly added, false if already exists *)
23}
24
25(** {1 URL Utilities} *)
26
27val repo_name_from_url : string -> string
28(** [repo_name_from_url url] extracts the repository name from a git URL. For
29 example, "https://github.com/mirage/eio.git" returns "eio". *)
30
31val normalize_url : string -> string
32(** [normalize_url url] ensures the URL has a "git+" prefix. *)
33
34val looks_like_url : string -> bool
35(** [looks_like_url s] returns [true] if [s] is plausibly a git URL or
36 filesystem path. Used to decide whether to treat an [add] argument as a
37 direct URL or as an opam package name that needs resolving. *)
38
39val resolve_name :
40 proc:_ Eio.Process.mgr ->
41 fs:Eio.Fs.dir_ty Eio.Path.t ->
42 ?opam_repo:Fpath.t ->
43 string ->
44 (string, string) Stdlib.result
45(** [resolve_name ~proc ~fs ?opam_repo name] resolves an opam package name to a
46 git dev-repo URL. Resolution order:
47
48 - If [opam_repo] is given, look up [name] in the local overlay first.
49 - Otherwise, shell out to [opam show <name> --field dev-repo] and parse the
50 result.
51
52 Returns [Ok url] on success or [Error msg] if neither path yielded a usable
53 URL. *)
54
55(** {1 Import Operations} *)
56
57val run :
58 sw:Eio.Switch.t ->
59 proc:_ Eio.Process.mgr ->
60 fs:Eio.Fs.dir_ty Eio.Path.t ->
61 target:Fpath.t ->
62 source:source ->
63 name:string option ->
64 dry_run:bool ->
65 unit ->
66 (result list, string) Stdlib.result
67(** [run ~sw ~proc ~fs ~target ~source ~name ~dry_run ()] imports a git
68 repository as a subtree into [target].
69
70 - [source] specifies the Git URL (with optional branch/ref/path) to import
71 - [name] overrides the default subtree directory name
72 - [dry_run] shows what would be imported without making changes
73
74 Returns the list of imported subtrees, or an error message. *)
75
76val git_url :
77 sw:Eio.Switch.t ->
78 proc:_ Eio.Process.mgr ->
79 fs:Eio.Fs.dir_ty Eio.Path.t ->
80 target:Fpath.t ->
81 url:string ->
82 branch:string option ->
83 ref_:string option ->
84 ?path:string ->
85 name:string option ->
86 dry_run:bool ->
87 unit ->
88 (result, string) Stdlib.result
89(** [git_url ~sw ~proc ~fs ~target ~url ~branch ~ref_ ?path ~name ~dry_run ()]
90 imports a single git URL as a subtree into [target]. When [path] is given,
91 [url] is treated as a monorepo and the subtree at [path] is extracted via
92 {!Git.Subtree.split} before being merged at [name]. Returns error if the
93 subtree directory already exists. *)
94
95val timestamp : unit -> string
96(** [timestamp ()] returns the current time in ISO 8601 format. *)