1// Package repository contains helper methods for working with a Git repo.
2package repository
3
4import (
5 "errors"
6 "io"
7 "time"
8
9 "github.com/ProtonMail/go-crypto/openpgp"
10 "github.com/go-git/go-billy/v5"
11
12 "github.com/git-bug/git-bug/util/lamport"
13)
14
15var (
16 // ErrNotARepo is the error returned when the git repo root can't be found
17 ErrNotARepo = errors.New("not a git repository")
18 // ErrClockNotExist is the error returned when a clock can't be found
19 ErrClockNotExist = errors.New("clock doesn't exist")
20 // ErrNotFound is the error returned when a git object can't be found
21 ErrNotFound = errors.New("ref not found")
22)
23
24// Repo represents a source code repository.
25type Repo interface {
26 RepoConfig
27 RepoKeyring
28 RepoCommon
29 RepoStorage
30 RepoIndex
31 RepoData
32 RepoBrowse
33
34 Close() error
35}
36
37type RepoCommonStorage interface {
38 RepoCommon
39 RepoStorage
40}
41
42// ClockedRepo is a Repo that also has Lamport clocks
43type ClockedRepo interface {
44 Repo
45 RepoClock
46}
47
48// RepoConfig access the configuration of a repository
49type RepoConfig interface {
50 // LocalConfig give access to the repository scoped configuration
51 LocalConfig() Config
52
53 // GlobalConfig give access to the global scoped configuration
54 GlobalConfig() Config
55
56 // AnyConfig give access to a merged local/global configuration
57 AnyConfig() ConfigRead
58}
59
60// RepoKeyring give access to a user-wide storage for secrets
61type RepoKeyring interface {
62 // Keyring give access to a user-wide storage for secrets
63 Keyring() Keyring
64}
65
66// RepoCommon represent the common function we want all repos to implement
67type RepoCommon interface {
68 // GetUserName returns the name the user has used to configure git
69 GetUserName() (string, error)
70
71 // GetUserEmail returns the email address that the user has used to configure git.
72 GetUserEmail() (string, error)
73
74 // GetCoreEditor returns the name of the editor that the user has used to configure git.
75 GetCoreEditor() (string, error)
76
77 // GetRemotes returns the configured remotes repositories.
78 GetRemotes() (map[string]string, error)
79
80}
81
82type LocalStorage interface {
83 billy.Filesystem
84 RemoveAll(path string) error
85}
86
87// RepoStorage give access to the filesystem
88type RepoStorage interface {
89 // LocalStorage return a billy.Filesystem giving access to $RepoPath/.git/git-bug
90 LocalStorage() LocalStorage
91}
92
93// RepoIndex gives access to full-text search indexes
94type RepoIndex interface {
95 GetIndex(name string) (Index, error)
96}
97
98// Index is a full-text search index
99type Index interface {
100 // IndexOne indexes one document, for the given ID. If the document already exist,
101 // it replaces it.
102 IndexOne(id string, texts []string) error
103
104 // IndexBatch start a batch indexing. The returned indexer function is used the same
105 // way as IndexOne, and the closer function complete the batch insertion.
106 IndexBatch() (indexer func(id string, texts []string) error, closer func() error)
107
108 // Search returns the list of IDs matching the given terms.
109 Search(terms []string) (ids []string, err error)
110
111 // DocCount returns the number of document in the index.
112 DocCount() (uint64, error)
113
114 // Remove delete one document in the index.
115 Remove(id string) error
116
117 // Clear empty the index.
118 Clear() error
119
120 // Close closes the index and make sure everything is safely written. After this call
121 // the index can't be used anymore.
122 Close() error
123}
124
125type Commit struct {
126 Hash Hash
127 Parents []Hash // hashes of the parents, if any
128 TreeHash Hash // hash of the git Tree
129 SignedData io.Reader // if signed, reader for the signed data (likely, the serialized commit)
130 Signature io.Reader // if signed, reader for the (non-armored) signature
131}
132
133// RepoData give access to the git data storage
134type RepoData interface {
135 // FetchRefs fetch git refs matching a directory prefix to a remote
136 // Ex: prefix="foo" will fetch any remote refs matching "refs/foo/*" locally.
137 // The equivalent git refspec would be "refs/foo/*:refs/remotes/<remote>/foo/*"
138 FetchRefs(remote string, prefixes ...string) (string, error)
139
140 // PushRefs push git refs matching a directory prefix to a remote
141 // Ex: prefix="foo" will push any local refs matching "refs/foo/*" to the remote.
142 // The equivalent git refspec would be "refs/foo/*:refs/foo/*"
143 //
144 // Additionally, PushRefs will update the local references in refs/remotes/<remote>/foo to match
145 // the remote state.
146 PushRefs(remote string, prefixes ...string) (string, error)
147
148 // StoreData will store arbitrary data and return the corresponding hash
149 StoreData(data []byte) (Hash, error)
150
151 // ReadData will attempt to read arbitrary data from the given hash
152 // Returns ErrNotFound if not found.
153 ReadData(hash Hash) ([]byte, error)
154
155 // StoreTree will store a mapping key-->Hash as a Git tree
156 StoreTree(mapping []TreeEntry) (Hash, error)
157
158 // ReadTree will return the list of entries in a Git tree
159 // The given hash could be from either a commit or a tree
160 // Returns ErrNotFound if not found.
161 ReadTree(hash Hash) ([]TreeEntry, error)
162
163 // StoreCommit will store a Git commit with the given Git tree
164 StoreCommit(treeHash Hash, parents ...Hash) (Hash, error)
165
166 // StoreSignedCommit will store a Git commit with the given Git tree. If signKey is not nil, the commit
167 // will be signed accordingly.
168 StoreSignedCommit(treeHash Hash, signKey *openpgp.Entity, parents ...Hash) (Hash, error)
169
170 // ReadCommit read a Git commit and returns some of its characteristic
171 // Returns ErrNotFound if not found.
172 ReadCommit(hash Hash) (Commit, error)
173
174 // ResolveRef returns the hash of the target commit of the given ref
175 // Returns ErrNotFound if not found.
176 ResolveRef(ref string) (Hash, error)
177
178 // UpdateRef will create or update a Git reference
179 UpdateRef(ref string, hash Hash) error
180
181 // RemoveRef will remove a Git reference
182 // RemoveRef is idempotent.
183 RemoveRef(ref string) error
184
185 // ListRefs will return a list of Git ref matching the given refspec
186 ListRefs(refPrefix string) ([]string, error)
187
188 // RefExist will check if a reference exists in Git
189 RefExist(ref string) (bool, error)
190
191 // CopyRef will create a new reference with the same value as another one
192 // Returns ErrNotFound if not found.
193 CopyRef(source string, dest string) error
194
195 // ListCommits will return the list of tree hashes of a ref, in chronological order
196 ListCommits(ref string) ([]Hash, error)
197}
198
199// RepoClock give access to Lamport clocks
200type RepoClock interface {
201 // AllClocks return all the known clocks
202 AllClocks() (map[string]lamport.Clock, error)
203
204 // GetOrCreateClock return a Lamport clock stored in the Repo.
205 // If the clock doesn't exist, it's created.
206 GetOrCreateClock(name string) (lamport.Clock, error)
207
208 // Increment is equivalent to c = GetOrCreateClock(name) + c.Increment()
209 Increment(name string) (lamport.Time, error)
210
211 // Witness is equivalent to c = GetOrCreateClock(name) + c.Witness(time)
212 Witness(name string, time lamport.Time) error
213}
214
215// RepoBrowse is implemented by all Repo implementations and provides
216// code-browsing endpoints (file tree, history, diffs).
217//
218// All methods accepting a ref parameter resolve it in order:
219// refs/heads/<ref>, refs/tags/<ref>, full ref name, raw commit hash.
220type RepoBrowse interface {
221 // Branches returns all local branches (refs/heads/*).
222 // IsDefault marks the branch HEAD points to.
223 // All other ref namespaces — including git-bug's internal refs
224 // (refs/bugs/, refs/identities/, …) — are excluded.
225 Branches() ([]BranchInfo, error)
226
227 // Tags returns all tags (refs/tags/*).
228 // All other ref namespaces are excluded.
229 Tags() ([]TagInfo, error)
230
231 // TreeAtPath returns the entries of the directory at path under ref.
232 // An empty path returns the root tree.
233 // Returns ErrNotFound if ref or path does not exist, or if path
234 // resolves to a blob rather than a tree.
235 // Symlinks appear as entries with ObjectType Symlink; they are not followed.
236 TreeAtPath(ref, path string) ([]TreeEntry, error)
237
238 // BlobAtPath returns the raw content, byte size, and git object hash of
239 // the file at path under ref. Returns ErrNotFound if ref or path does
240 // not exist, or if path resolves to a tree. Symlinks are not followed.
241 // The caller must close the reader.
242 BlobAtPath(ref, path string) (io.ReadCloser, int64, Hash, error)
243
244 // CommitLog returns at most limit commits reachable from ref, filtered
245 // to those touching path (empty = unrestricted). after is an exclusive
246 // cursor; pass Hash("") for no cursor. since and until bound the author
247 // date (inclusive); pass nil for no bound. Merge commits appear once,
248 // compared against the first parent only.
249 CommitLog(ref, path string, limit int, after Hash, since, until *time.Time) ([]CommitMeta, error)
250
251 // LastCommitForEntries returns the most recent commit that touched each
252 // name in the directory at path under ref. Entries not resolved within
253 // the implementation's depth limit are silently absent from the result.
254 LastCommitForEntries(ref, path string, names []string) (map[string]CommitMeta, error)
255
256 // CommitDetail returns the full metadata and changed-file list for a
257 // single commit identified by its hash. Diffs against the first parent
258 // only; the initial commit is diffed against the empty tree.
259 CommitDetail(hash Hash) (CommitDetail, error)
260
261 // CommitFileDiff returns the unified diff for a single file in a commit
262 // identified by its hash. Diffs against the first parent only; the
263 // initial commit is diffed against the empty tree.
264 CommitFileDiff(hash Hash, filePath string) (FileDiff, error)
265}
266
267// ClockLoader hold which logical clock need to exist for an entity and
268// how to create them if they don't.
269type ClockLoader struct {
270 // Clocks hold the name of all the clocks this loader deals with.
271 // Those clocks will be checked when the repo loads. If not present or broken,
272 // Witnesser will be used to create them.
273 Clocks []string
274 // Witnesser is a function that will initialize the clocks of a repo
275 // from scratch
276 Witnesser func(repo ClockedRepo) error
277}
278
279// TestedRepo is an extended ClockedRepo with functions for testing only
280type TestedRepo interface {
281 ClockedRepo
282 repoTest
283}
284
285// repoTest give access to test-only functions
286type repoTest interface {
287 // AddRemote add a new remote to the repository
288 AddRemote(name string, url string) error
289
290 // GetLocalRemote return the URL to use to add this repo as a local remote
291 GetLocalRemote() string
292
293 // EraseFromDisk delete this repository entirely from the disk
294 EraseFromDisk() error
295}