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
33 Close() error
34}
35
36type RepoCommonStorage interface {
37 RepoCommon
38 RepoStorage
39}
40
41// ClockedRepo is a Repo that also has Lamport clocks
42type ClockedRepo interface {
43 Repo
44 RepoClock
45}
46
47// RepoConfig access the configuration of a repository
48type RepoConfig interface {
49 // LocalConfig give access to the repository scoped configuration
50 LocalConfig() Config
51
52 // GlobalConfig give access to the global scoped configuration
53 GlobalConfig() Config
54
55 // AnyConfig give access to a merged local/global configuration
56 AnyConfig() ConfigRead
57}
58
59// RepoKeyring give access to a user-wide storage for secrets
60type RepoKeyring interface {
61 // Keyring give access to a user-wide storage for secrets
62 Keyring() Keyring
63}
64
65// RepoCommon represent the common function we want all repos to implement
66type RepoCommon interface {
67 // GetUserName returns the name the user has used to configure git
68 GetUserName() (string, error)
69
70 // GetUserEmail returns the email address that the user has used to configure git.
71 GetUserEmail() (string, error)
72
73 // GetCoreEditor returns the name of the editor that the user has used to configure git.
74 GetCoreEditor() (string, error)
75
76 // GetRemotes returns the configured remotes repositories.
77 GetRemotes() (map[string]string, error)
78
79 // GetPath returns the root directory path of the repository (the directory
80 // that contains the .git folder for bare repos, or the .git folder itself
81 // for bare clones). Returns an empty string for in-memory/mock repos.
82 GetPath() string
83}
84
85type LocalStorage interface {
86 billy.Filesystem
87 RemoveAll(path string) error
88}
89
90// RepoStorage give access to the filesystem
91type RepoStorage interface {
92 // LocalStorage return a billy.Filesystem giving access to $RepoPath/.git/git-bug
93 LocalStorage() LocalStorage
94}
95
96// RepoIndex gives access to full-text search indexes
97type RepoIndex interface {
98 GetIndex(name string) (Index, error)
99}
100
101// Index is a full-text search index
102type Index interface {
103 // IndexOne indexes one document, for the given ID. If the document already exist,
104 // it replaces it.
105 IndexOne(id string, texts []string) error
106
107 // IndexBatch start a batch indexing. The returned indexer function is used the same
108 // way as IndexOne, and the closer function complete the batch insertion.
109 IndexBatch() (indexer func(id string, texts []string) error, closer func() error)
110
111 // Search returns the list of IDs matching the given terms.
112 Search(terms []string) (ids []string, err error)
113
114 // DocCount returns the number of document in the index.
115 DocCount() (uint64, error)
116
117 // Remove delete one document in the index.
118 Remove(id string) error
119
120 // Clear empty the index.
121 Clear() error
122
123 // Close closes the index and make sure everything is safely written. After this call
124 // the index can't be used anymore.
125 Close() error
126}
127
128type Commit struct {
129 Hash Hash
130 Parents []Hash // hashes of the parents, if any
131 TreeHash Hash // hash of the git Tree
132 SignedData io.Reader // if signed, reader for the signed data (likely, the serialized commit)
133 Signature io.Reader // if signed, reader for the (non-armored) signature
134}
135
136// RepoData give access to the git data storage
137type RepoData interface {
138 // FetchRefs fetch git refs matching a directory prefix to a remote
139 // Ex: prefix="foo" will fetch any remote refs matching "refs/foo/*" locally.
140 // The equivalent git refspec would be "refs/foo/*:refs/remotes/<remote>/foo/*"
141 FetchRefs(remote string, prefixes ...string) (string, error)
142
143 // PushRefs push git refs matching a directory prefix to a remote
144 // Ex: prefix="foo" will push any local refs matching "refs/foo/*" to the remote.
145 // The equivalent git refspec would be "refs/foo/*:refs/foo/*"
146 //
147 // Additionally, PushRefs will update the local references in refs/remotes/<remote>/foo to match
148 // the remote state.
149 PushRefs(remote string, prefixes ...string) (string, error)
150
151 // StoreData will store arbitrary data and return the corresponding hash
152 StoreData(data []byte) (Hash, error)
153
154 // ReadData will attempt to read arbitrary data from the given hash
155 // Returns ErrNotFound if not found.
156 ReadData(hash Hash) ([]byte, error)
157
158 // StoreTree will store a mapping key-->Hash as a Git tree
159 StoreTree(mapping []TreeEntry) (Hash, error)
160
161 // ReadTree will return the list of entries in a Git tree
162 // The given hash could be from either a commit or a tree
163 // Returns ErrNotFound if not found.
164 ReadTree(hash Hash) ([]TreeEntry, error)
165
166 // StoreCommit will store a Git commit with the given Git tree
167 StoreCommit(treeHash Hash, parents ...Hash) (Hash, error)
168
169 // StoreSignedCommit will store a Git commit with the given Git tree. If signKey is not nil, the commit
170 // will be signed accordingly.
171 StoreSignedCommit(treeHash Hash, signKey *openpgp.Entity, parents ...Hash) (Hash, error)
172
173 // ReadCommit read a Git commit and returns some of its characteristic
174 // Returns ErrNotFound if not found.
175 ReadCommit(hash Hash) (Commit, error)
176
177 // ResolveRef returns the hash of the target commit of the given ref
178 // Returns ErrNotFound if not found.
179 ResolveRef(ref string) (Hash, error)
180
181 // UpdateRef will create or update a Git reference
182 UpdateRef(ref string, hash Hash) error
183
184 // RemoveRef will remove a Git reference
185 // RemoveRef is idempotent.
186 RemoveRef(ref string) error
187
188 // ListRefs will return a list of Git ref matching the given refspec
189 ListRefs(refPrefix string) ([]string, error)
190
191 // RefExist will check if a reference exist in Git
192 RefExist(ref string) (bool, error)
193
194 // CopyRef will create a new reference with the same value as another one
195 // Returns ErrNotFound if not found.
196 CopyRef(source string, dest string) error
197
198 // ListCommits will return the list of tree hashes of a ref, in chronological order
199 ListCommits(ref string) ([]Hash, error)
200}
201
202// CommitMeta holds the display-relevant metadata of a git commit.
203type CommitMeta struct {
204 Hash Hash
205 ShortHash string
206 Message string // first line only
207 AuthorName string
208 AuthorEmail string
209 Date time.Time
210 Parents []Hash
211}
212
213// RepoBrowse extends a repo with read-only methods needed for code browsing.
214// Implemented by GoGitRepo; not part of the core Repo interface because not
215// all repository implementations (e.g. in-memory test repos) need it.
216type RepoBrowse interface {
217 // GetDefaultBranch returns the short name of the branch HEAD points to.
218 GetDefaultBranch() (string, error)
219
220 // ReadCommitMeta reads full commit metadata including author and message.
221 ReadCommitMeta(hash Hash) (CommitMeta, error)
222
223 // CommitLog returns up to limit commits reachable from ref (short name or
224 // full ref), optionally filtered to commits that touch path.
225 // If after is non-empty, results start after that commit hash (pagination).
226 CommitLog(ref string, path string, limit int, after Hash) ([]CommitMeta, error)
227
228 // LastCommitForEntries walks the commit history once and returns the most
229 // recent commit that touched each named entry inside dirPath.
230 // dirPath is the directory being browsed (empty = repo root).
231 // names are the immediate child names (files/dirs) inside that directory.
232 // The returned map is keyed by entry name; missing entries were not found.
233 LastCommitForEntries(ref string, dirPath string, names []string) (map[string]CommitMeta, error)
234
235 // CommitDetail returns the full metadata for a single commit plus the list
236 // of files it changed relative to its first parent.
237 CommitDetail(hash Hash) (CommitDetail, error)
238}
239
240// ChangedFile describes a single file changed by a commit.
241type ChangedFile struct {
242 Path string // current path (or old path for deletions)
243 OldPath string // only set for renames
244 Status string // "added" | "modified" | "deleted" | "renamed"
245}
246
247// CommitDetail extends CommitMeta with the full message body and changed files.
248type CommitDetail struct {
249 CommitMeta
250 FullMessage string
251 Files []ChangedFile
252}
253
254// RepoClock give access to Lamport clocks
255type RepoClock interface {
256 // AllClocks return all the known clocks
257 AllClocks() (map[string]lamport.Clock, error)
258
259 // GetOrCreateClock return a Lamport clock stored in the Repo.
260 // If the clock doesn't exist, it's created.
261 GetOrCreateClock(name string) (lamport.Clock, error)
262
263 // Increment is equivalent to c = GetOrCreateClock(name) + c.Increment()
264 Increment(name string) (lamport.Time, error)
265
266 // Witness is equivalent to c = GetOrCreateClock(name) + c.Witness(time)
267 Witness(name string, time lamport.Time) error
268}
269
270// ClockLoader hold which logical clock need to exist for an entity and
271// how to create them if they don't.
272type ClockLoader struct {
273 // Clocks hold the name of all the clocks this loader deal with.
274 // Those clocks will be checked when the repo load. If not present or broken,
275 // Witnesser will be used to create them.
276 Clocks []string
277 // Witnesser is a function that will initialize the clocks of a repo
278 // from scratch
279 Witnesser func(repo ClockedRepo) error
280}
281
282// TestedRepo is an extended ClockedRepo with function for testing only
283type TestedRepo interface {
284 ClockedRepo
285 repoTest
286}
287
288// repoTest give access to test only functions
289type repoTest interface {
290 // AddRemote add a new remote to the repository
291 AddRemote(name string, url string) error
292
293 // GetLocalRemote return the URL to use to add this repo as a local remote
294 GetLocalRemote() string
295
296 // EraseFromDisk delete this repository entirely from the disk
297 EraseFromDisk() error
298}