1// Package repository contains helper methods for working with a Git repo.
2package repository
3
4import (
5 "errors"
6 "io"
7
8 "github.com/ProtonMail/go-crypto/openpgp"
9 "github.com/go-git/go-billy/v5"
10
11 "github.com/git-bug/git-bug/util/lamport"
12)
13
14var (
15 // ErrNotARepo is the error returned when the git repo root can't be found
16 ErrNotARepo = errors.New("not a git repository")
17 // ErrClockNotExist is the error returned when a clock can't be found
18 ErrClockNotExist = errors.New("clock doesn't exist")
19 // ErrNotFound is the error returned when a git object can't be found
20 ErrNotFound = errors.New("ref not found")
21)
22
23// Repo represents a source code repository.
24type Repo interface {
25 RepoConfig
26 RepoKeyring
27 RepoCommon
28 RepoStorage
29 RepoIndex
30 RepoData
31
32 Close() error
33}
34
35type RepoCommonStorage interface {
36 RepoCommon
37 RepoStorage
38}
39
40// ClockedRepo is a Repo that also has Lamport clocks
41type ClockedRepo interface {
42 Repo
43 RepoClock
44}
45
46// RepoConfig access the configuration of a repository
47type RepoConfig interface {
48 // LocalConfig give access to the repository scoped configuration
49 LocalConfig() Config
50
51 // GlobalConfig give access to the global scoped configuration
52 GlobalConfig() Config
53
54 // AnyConfig give access to a merged local/global configuration
55 AnyConfig() ConfigRead
56}
57
58// RepoKeyring give access to a user-wide storage for secrets
59type RepoKeyring interface {
60 // Keyring give access to a user-wide storage for secrets
61 Keyring() Keyring
62}
63
64// RepoCommon represent the common function we want all repos to implement
65type RepoCommon interface {
66 // GetUserName returns the name the user has used to configure git
67 GetUserName() (string, error)
68
69 // GetUserEmail returns the email address that the user has used to configure git.
70 GetUserEmail() (string, error)
71
72 // GetCoreEditor returns the name of the editor that the user has used to configure git.
73 GetCoreEditor() (string, error)
74
75 // GetRemotes returns the configured remotes repositories.
76 GetRemotes() (map[string]string, error)
77}
78
79type LocalStorage interface {
80 billy.Filesystem
81 RemoveAll(path string) error
82}
83
84// RepoStorage give access to the filesystem
85type RepoStorage interface {
86 // LocalStorage return a billy.Filesystem giving access to $RepoPath/.git/git-bug
87 LocalStorage() LocalStorage
88}
89
90// RepoIndex gives access to full-text search indexes
91type RepoIndex interface {
92 GetIndex(name string) (Index, error)
93}
94
95// Index is a full-text search index
96type Index interface {
97 // IndexOne indexes one document, for the given ID. If the document already exist,
98 // it replaces it.
99 IndexOne(id string, texts []string) error
100
101 // IndexBatch start a batch indexing. The returned indexer function is used the same
102 // way as IndexOne, and the closer function complete the batch insertion.
103 IndexBatch() (indexer func(id string, texts []string) error, closer func() error)
104
105 // Search returns the list of IDs matching the given terms.
106 Search(terms []string) (ids []string, err error)
107
108 // DocCount returns the number of document in the index.
109 DocCount() (uint64, error)
110
111 // Remove delete one document in the index.
112 Remove(id string) error
113
114 // Clear empty the index.
115 Clear() error
116
117 // Close closes the index and make sure everything is safely written. After this call
118 // the index can't be used anymore.
119 Close() error
120}
121
122type Commit struct {
123 Hash Hash
124 Parents []Hash // hashes of the parents, if any
125 TreeHash Hash // hash of the git Tree
126 SignedData io.Reader // if signed, reader for the signed data (likely, the serialized commit)
127 Signature io.Reader // if signed, reader for the (non-armored) signature
128}
129
130// RepoData give access to the git data storage
131type RepoData interface {
132 // FetchRefs fetch git refs matching a directory prefix to a remote
133 // Ex: prefix="foo" will fetch any remote refs matching "refs/foo/*" locally.
134 // The equivalent git refspec would be "refs/foo/*:refs/remotes/<remote>/foo/*"
135 FetchRefs(remote string, prefixes ...string) (string, error)
136
137 // PushRefs push git refs matching a directory prefix to a remote
138 // Ex: prefix="foo" will push any local refs matching "refs/foo/*" to the remote.
139 // The equivalent git refspec would be "refs/foo/*:refs/foo/*"
140 //
141 // Additionally, PushRefs will update the local references in refs/remotes/<remote>/foo to match
142 // the remote state.
143 PushRefs(remote string, prefixes ...string) (string, error)
144
145 // StoreData will store arbitrary data and return the corresponding hash
146 StoreData(data []byte) (Hash, error)
147
148 // ReadData will attempt to read arbitrary data from the given hash
149 // Returns ErrNotFound if not found.
150 ReadData(hash Hash) ([]byte, error)
151
152 // StoreTree will store a mapping key-->Hash as a Git tree
153 StoreTree(mapping []TreeEntry) (Hash, error)
154
155 // ReadTree will return the list of entries in a Git tree
156 // The given hash could be from either a commit or a tree
157 // Returns ErrNotFound if not found.
158 ReadTree(hash Hash) ([]TreeEntry, error)
159
160 // StoreCommit will store a Git commit with the given Git tree
161 StoreCommit(treeHash Hash, parents ...Hash) (Hash, error)
162
163 // StoreSignedCommit will store a Git commit with the given Git tree. If signKey is not nil, the commit
164 // will be signed accordingly.
165 StoreSignedCommit(treeHash Hash, signKey *openpgp.Entity, parents ...Hash) (Hash, error)
166
167 // ReadCommit read a Git commit and returns some of its characteristic
168 // Returns ErrNotFound if not found.
169 ReadCommit(hash Hash) (Commit, error)
170
171 // ResolveRef returns the hash of the target commit of the given ref
172 // Returns ErrNotFound if not found.
173 ResolveRef(ref string) (Hash, error)
174
175 // UpdateRef will create or update a Git reference
176 UpdateRef(ref string, hash Hash) error
177
178 // RemoveRef will remove a Git reference
179 // RemoveRef is idempotent.
180 RemoveRef(ref string) error
181
182 // ListRefs will return a list of Git ref matching the given refspec
183 ListRefs(refPrefix string) ([]string, error)
184
185 // RefExist will check if a reference exist in Git
186 RefExist(ref string) (bool, error)
187
188 // CopyRef will create a new reference with the same value as another one
189 // Returns ErrNotFound if not found.
190 CopyRef(source string, dest string) error
191
192 // ListCommits will return the list of tree hashes of a ref, in chronological order
193 ListCommits(ref string) ([]Hash, error)
194}
195
196// RepoClock give access to Lamport clocks
197type RepoClock interface {
198 // AllClocks return all the known clocks
199 AllClocks() (map[string]lamport.Clock, error)
200
201 // GetOrCreateClock return a Lamport clock stored in the Repo.
202 // If the clock doesn't exist, it's created.
203 GetOrCreateClock(name string) (lamport.Clock, error)
204
205 // Increment is equivalent to c = GetOrCreateClock(name) + c.Increment()
206 Increment(name string) (lamport.Time, error)
207
208 // Witness is equivalent to c = GetOrCreateClock(name) + c.Witness(time)
209 Witness(name string, time lamport.Time) error
210}
211
212// ClockLoader hold which logical clock need to exist for an entity and
213// how to create them if they don't.
214type ClockLoader struct {
215 // Clocks hold the name of all the clocks this loader deal with.
216 // Those clocks will be checked when the repo load. If not present or broken,
217 // Witnesser will be used to create them.
218 Clocks []string
219 // Witnesser is a function that will initialize the clocks of a repo
220 // from scratch
221 Witnesser func(repo ClockedRepo) error
222}
223
224// TestedRepo is an extended ClockedRepo with function for testing only
225type TestedRepo interface {
226 ClockedRepo
227 repoTest
228}
229
230// repoTest give access to test only functions
231type repoTest interface {
232 // AddRemote add a new remote to the repository
233 AddRemote(name string, url string) error
234
235 // GetLocalRemote return the URL to use to add this repo as a local remote
236 GetLocalRemote() string
237
238 // EraseFromDisk delete this repository entirely from the disk
239 EraseFromDisk() error
240}