1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
// Package furgit provides low-level git operations.
//
// Furgit is an unfinished research project,
// and is not suitable for production.
//
// The architecture is rather deliberate
// and the parts that exist
// have been built carefully
// (to the best of our capability)
// and tested against git as the canonical oracle, etc.
//
// However, the API is not yet settled at all;
// we may revise interfaces and behaviour at any time,
// to incorporate findings from ongoing audits,
// including full rearchitectures.
// Consumers that depend on a 0.x version of furgit
// will need to revise their usages
// every few days or weeks.
//
// Therefore, you should probably not use furgit.
// Consider using [go-git],
// which is mature and has API stability promises,
// or simply use [os/exec] to upstream git,
// which is sufficient for many purposes.
//
// # Overall architecture
//
// Git libraries often center on a central repository type where all
// data structures and operations are hosted.
// Furgit inverts that:
// objects are plain values that do not provide access to the storer that loaded them,
// object storage and ref storage are sets of narrow interfaces
// that consist only of methods that are reasonable for all implementations,
// and every higher-level operation,
// such as commit traversal, reachability analysis, and recursive peeling,
// is built over those interfaces as independent subsystems.
//
// # Contract labels
//
// Many furgit APIs use short labels to document
// concurrency, dependency ownership, value lifetime, and other behavior.
//
// When both a type and one of its methods
// specify conflicting labels,
// the method-label takes precedence.
//
// Concurrency labels:
//
// - MT-Safe: safe for concurrent use.
// - MT-Unsafe: not safe for concurrent use without external synchronization.
//
// Dependency labels:
//
// - Deps-Owned: the receiver takes ownership of all supplied dependencies
// where ownership is a reasonable concept.
// - Deps-Borrowed: the value borrows supplied dependencies.
// Usually also labelled with Life-Parent
// unless those dependencies are not retained past construction.
// - Deps-Mixed: some are mixed while others are borrowed.
// The documentation should specify further.
//
// Lifetime labels:
//
// - Life-Independent: returned values remain valid
// independently of the parent or provider.
// - Life-Parent: returned values are only valid
// while the parent or provider remains valid.
// - Life-Call: returned values are only valid
// for the duration of the current call, callback, or hook invocation.
//
// Close labels:
//
// - Close-Caller: the caller must close the returned value.
// - Close-No: the caller must not close the returned value,
// even if the returned value has a Close method.
//
// Idempotency labels:
//
// - Idem-Yes: action is idempotent.
// - Idem-2UB: action is not idempotent;
// repeated use is undefined behavior.
//
// Mutation labels:
//
// - Mut-No: returned values must not be mutated.
//
// These labels describe the API contract only,
// and do not imply any specific implementation strategy.
//
// Concrete implementations of capability interfaces
// generally inherit the contract documented by the interfaces they satisfy.
// Implementation docs focus on additional guarantees
// and implementation-specific behavior,
// but users are advised not to rely on them
// in order to maintain the flexibility of switching implementations.
//
// [go-git]: https://github.com/go-git/go-git
package furgit
|
