gazagnaire.org
Git object storage and pack files for Eio
1(* Copyright (c) 2013-2017 Thomas Gazagnaire <thomas@gazagnaire.org>
2 Copyright (c) 2017-2024 Romain Calascibetta <romain.calascibetta@gmail.com>
3 Copyright (c) 2024-2026 Thomas Gazagnaire <thomas@gazagnaire.org>
4
5 Permission to use, copy, modify, and distribute this software for any
6 purpose with or without fee is hereby granted, provided that the above
7 copyright notice and this permission notice appear in all copies.
8
9 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. *)
16
17(** Git object format implementation in pure OCaml.
18
19 This library provides type-safe encoding and decoding of Git objects: blobs,
20 trees, commits, and tags. It is derived from
21 {{:https://github.com/mirage/ocaml-git}mirage/ocaml-git} and
22 {{:https://github.com/robur-coop/carton}robur-coop/carton}.
23
24 {1 Object types}
25
26 Git stores four types of objects:
27 - {!Blob}: File contents
28 - {!Tree}: Directory listings (entries with mode, name, and hash)
29 - {!Commit}: Snapshots with metadata (tree, parents, author, committer,
30 message)
31 - {!Tag}: Named references to objects with optional signature
32
33 {1 Example}
34
35 {[
36 (* Create a blob *)
37 let blob = Git.Blob.of_string "Hello, World!\n"
38 let blob_hash = Git.Blob.digest blob
39
40 (* Create a tree entry *)
41 let entry = Git.Tree.entry ~perm:`Normal ~name:"hello.txt" blob_hash
42 let tree = Git.Tree.v [ entry ]
43 let tree_hash = Git.Tree.digest tree
44
45 (* Create a commit *)
46 let author = Git.User.v ~name:"Alice" ~email:"alice@example.com" ()
47
48 let commit =
49 Git.Commit.v ~tree:tree_hash ~author ~committer:author
50 (Some "Initial commit")
51
52 let commit_hash = Git.Commit.digest commit
53 ]} *)
54
55module Hash = Hash
56(** Git object hashes (SHA-1). *)
57
58module User = User
59(** Git user information (author/committer). *)
60
61module Blob = Blob
62(** Git blob objects (file contents). *)
63
64module Tree = Tree
65(** Git tree objects (directory listings). *)
66
67module Commit = Commit
68(** Git commit objects. *)
69
70module Tag = Tag
71(** Git tag objects. *)
72
73module Value = Value
74(** Git values (union of all object types). *)
75
76module Reference = Reference
77(** Git references (branches, tags, HEAD). *)
78
79module Pack = Pack
80(** Git pack files (compressed object storage). *)
81
82module Pack_index = Pack_index
83(** Git pack index files (fast object lookup). *)
84
85module Repository = Repository
86(** Git repository access (loose objects + pack files). *)
87
88module Rev_list = Rev_list
89(** Commit graph traversal and topological ordering. *)
90
91module Subtree = Subtree
92(** Fast subtree split with persistent caching. *)
93
94module Config = Config
95(** Git config file parsing (.git/config). *)
96
97module Index = Index
98(** Git index (staging area) operations. *)
99
100module Remote = Remote
101(** Git remote queries via smart HTTP protocol. *)
102
103module Diff = Diff
104(** Git diff operations. *)
105
106module Worktree = Worktree
107(** Git worktree operations. *)