Line data Source code
1 : /*!
2 : * \file esys/repo/gitbase.h
3 : * \brief Base class for git client implementation
4 : *
5 : * \cond
6 : * __legal_b__
7 : *
8 : * Copyright (c) 2020-2023 Michel Gillet
9 : * Distributed under the MIT License.
10 : * (See accompanying file LICENSE.txt or
11 : * copy at https://opensource.org/licenses/MIT)
12 : *
13 : * __legal_e__
14 : * \endcond
15 : *
16 : */
17 :
18 : #pragma once
19 :
20 : #include "esys/repo/esysrepo_defs.h"
21 : #include "esys/repo/git/aheadbehind.h"
22 : #include "esys/repo/git/branches.h"
23 : #include "esys/repo/git/cloneoptions.h"
24 : #include "esys/repo/git/commit.h"
25 : #include "esys/repo/git/diff.h"
26 : #include "esys/repo/git/fetchstep.h"
27 : #include "esys/repo/git/mergeanalysisresult.h"
28 : #include "esys/repo/git/noteid.h"
29 : #include "esys/repo/git/person.h"
30 : #include "esys/repo/git/progress.h"
31 : #include "esys/repo/git/remote.h"
32 : #include "esys/repo/git/repostatus.h"
33 : #include "esys/repo/git/resettype.h"
34 : #include "esys/repo/git/sshbackend.h"
35 : #include "esys/repo/git/walkcommit.h"
36 : #include "esys/repo/result.h"
37 : #include "esys/repo/result_t.h"
38 :
39 : #include "esys/repo/progresscallbackbase.h"
40 :
41 : #include <esys/log/user.h>
42 :
43 : #include <chrono>
44 : #include <map>
45 : #include <memory>
46 : #include <mutex>
47 : #include <string>
48 : #include <vector>
49 :
50 : //<swig_inc/>
51 :
52 : //<swig>%shared_ptr(esys::repo::GitBase);</swig>
53 :
54 : namespace esys::repo
55 : {
56 :
57 : /*! \class GitBase esys/repo/gitbase.h "esys/repo/gitbase.h"
58 : * \brief Base class for git client implementation
59 : */
60 : class ESYSREPO_API GitBase : public log::User
61 : {
62 : public:
63 : using GeneratorType = std::shared_ptr<GitBase> (*)();
64 :
65 : //! Default constructor
66 : GitBase();
67 :
68 : //! Destructor
69 : ~GitBase() override;
70 :
71 : //! Set the author to be used for commit and notes
72 : /*!
73 : * \param[in] person the person to use as author
74 : */
75 : void set_author(std::shared_ptr<git::Person> person);
76 :
77 : //! Get the author to be used for commit and notes
78 : /*!
79 : * \return the person used as Author
80 : */
81 : std::shared_ptr<git::Person> get_author() const;
82 :
83 : //! Set the committer to be used for commit and notes
84 : /*!
85 : * \param[in] person the person to use as committer
86 : */
87 : void set_committer(std::shared_ptr<git::Person> person);
88 :
89 : //! Get the committer to be used for commit and notes
90 : /*!
91 : * \return the person used as committer
92 : */
93 : std::shared_ptr<git::Person> get_committer() const;
94 :
95 : //! Open a git repository for inspection
96 : /*!
97 : * \param[in] folder the folder where is the git repository
98 : * \return 0 if successful, < 0 otherwise
99 : */
100 : //<swig>%rename(open_folder) open;</swig>
101 : virtual Result open(const std::string &folder) = 0;
102 :
103 : //! Tells if the git repository is open or not
104 : /*!
105 : * \return true if open, false otherwise
106 : */
107 : virtual bool is_open() = 0;
108 :
109 : //! Initialize a bare git repository in a given folder
110 : /*!
111 : * \param[in] folder_path the folder where to create the bare git repository
112 : * \return 0 if successful, < 0 otherwise
113 : */
114 : virtual Result init_bare(const std::string &folder_path) = 0;
115 :
116 : //! Initialize a non-bare git repository in a given folder
117 : /*!
118 : * \param[in] folder_path the folder where to create the git repository
119 : * \return 0 if successful, < 0 otherwise
120 : */
121 : virtual Result init(const std::string &folder_path) = 0;
122 :
123 : //! Close a git repository
124 : /*!
125 : * \return 0 if successful, < 0 otherwise
126 : */
127 : virtual Result close() = 0;
128 :
129 : //! Close a git repository when an error occured
130 : virtual void close_on_error() = 0;
131 :
132 : //! Get all remotes of an open git repository
133 : /*!
134 : * \param[out] remotes vector with all the remotes of the open git repository
135 : * \return 0 if successful, < 0 otherwise
136 : */
137 : virtual Result get_remotes(std::vector<git::Remote> &remotes) = 0;
138 :
139 : //! Get the branch and the remote of the head
140 : /*!
141 : * \param[out] branch the branch of the head
142 : * \param[out] remote the remote of the head
143 : * \return 0 if successful, < 0 otherwise
144 : */
145 : virtual Result get_head_branch_remote(git::Branch &branch, git::Remote &remote) = 0;
146 :
147 : //! Add a remote to the local git repository
148 : /*!
149 : * \param[in] name the name of the remote
150 : * \param[in] url the url of the remote
151 : * \return 0 if successful, < 0 otherwise
152 : */
153 : virtual Result add_remote(const std::string &name, const std::string &url) = 0;
154 :
155 : //! Get all branches of an open git repository
156 : /*!
157 : * \param[out] branches vector with all the branches of the open git repository
158 : * \param[in] branch_type tells if the local or remote branches are requested
159 : * \return 0 if successful, < 0 otherwise
160 : */
161 : virtual Result get_branches(git::Branches &branches, git::BranchType branch_type = git::BranchType::LOCAL) = 0;
162 :
163 : //! Clone a remote git repository given it's address and path where to clone it
164 : /*!
165 : * \param[in] url the url for the repository to clone
166 : * \param[in] path where to clone the repository
167 : * \param[in] rev optional named tip (branch or tag); honored only if
168 : * ``options.checkout_rev``. Not a raw commit SHA.
169 : * \param[in] options checkout_rev / single_branch (defaults = legacy clone)
170 : * \return 0 if successful, < 0 otherwise
171 : */
172 : virtual Result clone(const std::string &url, const std::string &path, const std::string &rev,
173 : const git::CloneOptions &options) = 0;
174 :
175 : //! Clone with default options (legacy: ``rev`` ignored; remote default tip only)
176 41 : Result clone(const std::string &url, const std::string &path, const std::string &rev = "")
177 : {
178 41 : return clone(url, path, rev, git::CloneOptions());
179 : }
180 :
181 : //! Checkout a given branch of an open git repository
182 : /*!
183 : * \param[in] branch the name of the branch to checkout
184 : * \param[in] force if the cloning will be forced or not
185 : * \return 0 if successful, < 0 otherwise
186 : */
187 : virtual Result checkout(const std::string &branch, bool force = false) = 0;
188 :
189 : //! Reset the git repo to a given commit
190 : /*!
191 : * \param[in] commit the commit to reset the git repo to
192 : * \param[in] type the type of reset to do
193 : * \return 0 if successful, < 0 otherwise
194 : */
195 : virtual Result reset(const git::CommitHash &commit, git::ResetType type = git::ResetType::SOFT) = 0;
196 :
197 : //! Fast foward git repo to a given commit
198 : /*!
199 : * \param[in] commit the commit to reset the git repo to
200 : * \return 0 if successful, < 0 otherwise
201 : */
202 : virtual Result fastforward(const git::CommitHash &commit) = 0;
203 :
204 : //! Get the last commit of the HEAD
205 : /*!
206 : * \param[out] commit the commit hash
207 : * \return 0 if successful, < 0 otherwise
208 : */
209 : virtual Result get_last_commit(git::CommitHash &commit) = 0;
210 :
211 : //! Get the last commit of the HEAD
212 : /*!
213 : * \param[out] commit the commit data
214 : * \return 0 if successful, < 0 otherwise
215 : */
216 : virtual Result get_last_commit(git::Commit &commit, bool get_all_notes = false) = 0;
217 :
218 : //! Get the nth parent of a given commit
219 : /*!
220 : * If nth_parent is zero, the parent commit is simply the given commit.
221 : * If nth_parent is 1, it will return the parent of the commit.
222 : * If nth_parent is 2, it will return the grandparent of the commit.
223 : *
224 : * In the case of an octopus merge, it will take the first parent of the list.
225 : *
226 : * \param[in] commit the commit data
227 : * \param[out] parent the parent commit data
228 : * \param[in] nth_parent the nth parent starting
229 : * \return 0 if successful, < 0 otherwise
230 : */
231 : virtual Result get_parent_commit(const git::CommitHash &commit, git::CommitHash &parent, int nth_parent = 1) = 0;
232 :
233 : //! Tells if there are changes in the git repo
234 : /*!
235 : * \param[out] dirty true if the git repo is dirty, there are modification; false otherwise
236 : * \return 0 if successful, < 0 otherwise
237 : */
238 : virtual Result is_dirty(bool &dirty) = 0;
239 :
240 : //! Tells if git repo is detached or not
241 : /*!
242 : * \param[out] detached true if the git repo is detached; false otherwise
243 : * \return 0 if successful, < 0 otherwise
244 : */
245 : virtual Result is_detached(bool &detached) = 0;
246 :
247 : //! Get the status of the repository
248 : /*!
249 : * \param[out] status the status of the repository
250 : * \return 0 if successful, < 0 otherwise
251 : */
252 : virtual Result get_status(git::RepoStatus &status) = 0;
253 :
254 : //! Tells if a SSH agent is running or not
255 : /*!
256 : * \param[in] log_once if true, log only once if the SSH is detected
257 : * \return true if a SSH agent is running, false otherwise
258 : */
259 : virtual Result_t<bool> is_ssh_agent_running(bool log_once = true) = 0;
260 :
261 : //! Detect and optionally log if a SSH agent is found
262 : /*!
263 : * \param[in] log_once if true, log only once if the SSH is detected
264 : */
265 : virtual void detect_ssh_agent(bool log_once = true) = 0;
266 :
267 : //! Tell if an SSH backend was compiled into the active Git implementation
268 : /*!
269 : * Process-wide (not per Git instance). Dispatches to the registered
270 : * implementation from GitMngr.
271 : *
272 : * \param[in] backend the SSH backend
273 : * \return true if compiled in / supported by the implementation
274 : */
275 : static bool is_ssh_backend_supported(git::SshBackend backend);
276 :
277 : //! Tell if an SSH backend can be used at runtime
278 : /*!
279 : * Process-wide (not per Git instance). For LibSSH2 this matches
280 : * is_ssh_backend_supported. For Exec, also checks that an OpenSSH-compatible
281 : * client is configured or findable (GIT_SSH_COMMAND, GIT_SSH, or ssh on PATH).
282 : *
283 : * \param[in] backend the SSH backend
284 : * \param[in] force if true, refresh the Exec client probe cache
285 : * \return true if the backend can be selected for SSH operations
286 : */
287 : static bool is_ssh_backend_available(git::SshBackend backend, bool force = false);
288 :
289 : //! Select the process-wide SSH backend
290 : /*!
291 : * \param[in] backend the SSH backend to use for subsequent SSH operations
292 : * \return OK if successful, error if unsupported or the underlying library failed
293 : */
294 : static Result set_ssh_backend(git::SshBackend backend);
295 :
296 : //! Get the process-wide SSH backend currently selected
297 : /*!
298 : * \return the active backend, or an error if SSH is unavailable
299 : */
300 : static Result_t<git::SshBackend> get_ssh_backend();
301 :
302 : //! Check what kind of merge would required to merge the given branch to the git repo
303 : /*!
304 : * \param[in] refs the list of references/branches which would be merged
305 : * \param[out] merge_analysis_result the type of merge which would be required
306 : * \param[out] commits the list of commits which would be merged
307 : * \return 0 if successful, < 0 otherwise
308 : */
309 : virtual Result merge_analysis(const std::vector<std::string> &refs, git::MergeAnalysisResult &merge_analysis_result,
310 : std::vector<git::CommitHash> &commits) = 0;
311 :
312 : //! Do a fetch on a git repo from the given remote
313 : /*!
314 : * \param[in] remote the remote to use, or uses the default one if not given
315 : * \return 0 if successful, < 0 otherwise
316 : */
317 : virtual Result fetch(const std::string &remote = "") = 0;
318 :
319 : //! Fetch one extra refspec (needed after a single-branch clone, ADR-0030 / ADR-0037)
320 : virtual Result fetch_refspec(const std::string &refspec, const std::string &remote = "") = 0;
321 :
322 : //! Init and update Git submodules of an existing work tree (ADR-0032)
323 : /*!
324 : * \param[in] path absolute path to the parent repository work tree
325 : * \param[in] recursive also update nested submodules
326 : * \return OK if successful
327 : */
328 : virtual Result update_submodules(const std::string &path, bool recursive = true) = 0;
329 :
330 : //! fetch all notes
331 : /*!
332 : * \param[in] arg the remote
333 : */
334 : virtual Result fetch_all_notes(const std::string &remote = "") = 0;
335 :
336 : //! reset to parent
337 : /*!
338 : * \param[in] 1 the nth parent
339 : */
340 : virtual Result reset_to_parent(int nth_parent = 1);
341 :
342 : virtual Result_t<bool> has_branch(const std::string &name,
343 : git::BranchType branch_type = git::BranchType::LOCAL) = 0;
344 :
345 : virtual Result get_hash(const std::string &revision, std::string &hash,
346 : git::BranchType branch_type = git::BranchType::REMOTE) = 0;
347 :
348 : //! Walks through all the commits starting from the HEAD
349 : /*!
350 : * \param[in] walk_commit the instance used to handle the commits
351 : * \return 0 if successful, < 0 otherwise
352 : */
353 : virtual Result walk_commits(std::shared_ptr<git::WalkCommit> walk_commit) = 0;
354 :
355 : //! Get the diff between a commit and its parent
356 : /*!
357 : * \param[in] commit_hash the commit to get the diff from
358 : * \param[out] diff the diff with the parent if any
359 : * \return 0 if successful, < 0 otherwise
360 : */
361 : virtual Result diff(const git::CommitHash &commit_hash, std::shared_ptr<git::Diff> diff) = 0;
362 :
363 : //! Get the the number of commits ahead or behind between a branch and its upstream
364 : /*!
365 : * \param[out] ahead_behind number of commits ahead or behind
366 : * \param[in] local_branch the local_branch
367 : * \return 0 if successful, < 0 otherwise
368 : */
369 : virtual Result get_ahead_behind(git::AheadBehind &ahead_behind, const git::Branch &local_branch) = 0;
370 :
371 : //! Get the the number of commits ahead or behind between 2 references
372 : /*!
373 : * \param[out] ahead_behind number of commits ahead or behind
374 : * \param[in] first_ref the first reference
375 : * \param[in] second_ref the second reference
376 : * \return 0 if successful, < 0 otherwise
377 : */
378 : virtual Result get_ahead_behind(git::AheadBehind &ahead_behind, const std::string &first_ref,
379 : const std::string &second_ref) = 0;
380 :
381 : //! Tells if a folder is a git repository
382 : /*!
383 : * \param[in] path the path of the folder
384 : * \return true if it's a git repository, false otherwise
385 : */
386 : static bool is_repo(const std::string &path);
387 :
388 : //! Set the id of this instance
389 : /*!
390 : * \param[in] id the id of this instance
391 : */
392 : void set_id(std::size_t id);
393 :
394 : //! Get the id of this instance
395 : /*!
396 : * \return the id of this instance
397 : */
398 : std::size_t get_id() const;
399 :
400 : //! Set if debug information should be printed
401 : /*!
402 : * \param[in] debug true if debug information should be printed
403 : */
404 : void set_debug(bool debug);
405 :
406 : //! Get if debug information should be printed
407 : /*!
408 : * \return true if debug information should be printed, false otherwise
409 : */
410 : bool get_debug() const;
411 :
412 : //! Get the version of the library used to implement the functionality
413 : /*!
414 : * \return the version of the library used to implement the functionality
415 : */
416 : virtual const std::string &get_version() = 0;
417 :
418 : //! Get the name of the library used to implement the functionality
419 : /*!
420 : * \return the name of the library used to implement the functionality
421 : */
422 : virtual const std::string &get_lib_name() = 0;
423 :
424 : //! handle sideband progress
425 : /*!
426 : * \param[in] text the text
427 : */
428 : int handle_sideband_progress(const std::string &text);
429 :
430 : //! handle transfer progress
431 : /*!
432 : * \param[in] progress the progress
433 : */
434 : int handle_transfer_progress(const git::Progress &progress);
435 :
436 : //! Set the progress
437 : /*!
438 : * \param[in] progress the progress
439 : */
440 : void set_progress(const git::Progress &progress);
441 :
442 : //! Get the progress
443 : /*!
444 : * \return the progress
445 : */
446 : void get_progress(git::Progress &progress);
447 :
448 : //! Set the progress callback
449 : /*!
450 : * \param[in] progress_callback the progress callback
451 : */
452 : void set_progress_callback(ProgressCallbackBase *progress_callback);
453 : ProgressCallbackBase *get_progress_callback();
454 :
455 : virtual Result add_note(git::NoteId ¬e_id, const std::string &reference, const std::string &message,
456 : bool overwrite = false) = 0;
457 :
458 : //! remove note
459 : /*!
460 : * \param[in] node_id the node id
461 : */
462 : virtual Result remove_note(const git::NoteId &node_id) = 0;
463 :
464 : //! remove note
465 : /*!
466 : * \param[in] commit_hash the commit hash
467 : * \param[in] reference the reference
468 : */
469 : virtual Result remove_note(const git::CommitHash &commit_hash, const std::string &reference) = 0;
470 :
471 : //! remove note last commit
472 : /*!
473 : * \param[in] reference the reference
474 : */
475 : virtual Result remove_note_last_commit(const std::string &reference) = 0;
476 :
477 : virtual Result push(const std::string &remote, const std::string &src_ref = "",
478 : const std::string &dst_ref = "") = 0;
479 : //! push notes
480 : /*!
481 : * \param[in] remote the remote
482 : * \param[in] arg the reference
483 : */
484 : virtual Result push_notes(const std::string &remote, const std::string &reference = "") = 0;
485 :
486 : //! Clear all note references
487 : /*!
488 : * \return the name of the library used to implement the functionality
489 : */
490 : void clear_notes_ref();
491 :
492 : //! Add a notes reference
493 : /*!
494 : * \param[in] notes_ref the notes reference to add
495 : */
496 : int add_notes_ref(const std::string ¬es_ref);
497 :
498 : //! Get all notes reference
499 : /*!
500 : * \return the notes references
501 : */
502 : std::vector<std::string> &get_notes_references();
503 :
504 : //! Get all notes reference
505 : /*!
506 : * \return the notes references
507 : */
508 : const std::vector<std::string> &get_notes_references() const;
509 :
510 : //! Decode the information sent by the remote git server
511 : /*!
512 : * \param[in] txt the text received
513 : * \param[out] fetch_step the fetch step we are at
514 : * \param[out] done true if the detected fetch step is done
515 : * \param[out] percentage the percentange done of the detected fetch step
516 : * \return 0 if the decoding was successful, < 0 if an error occurred
517 : */
518 : static int decode_sideband_progress(const std::string &txt, git::Progress &progress);
519 :
520 : //! Notify the progress callback (rate-limited).
521 : /*!
522 : * Throttle decision first (no lock). On emit: cache progress and invoke the
523 : * ProgressCallback. At most about every 50 ms, plus on started/done/fetch-step
524 : * changes — so libgit2 transfer ticks do not flood TaskBase / TUI.
525 : */
526 : void notify_progress_throttled(const git::Progress &progress);
527 :
528 : //! cmd start
529 : virtual void cmd_start();
530 :
531 : //! cmd end
532 : virtual void cmd_end();
533 :
534 : //! open time
535 : virtual void open_time();
536 :
537 : //! close time
538 : virtual void close_time();
539 :
540 : //! Get the open time
541 : /*!
542 : * \return the open time
543 : */
544 : virtual uint64_t get_open_time();
545 :
546 : //! Get the last cmd elapsed time
547 : /*!
548 : * \return the last cmd elapsed time
549 : */
550 : virtual uint64_t get_last_cmd_elapsed_time();
551 :
552 : //! Hybrid: ms spent reopening libgit2 after clone/fetch; others return 0
553 : /*!
554 : * Clears the stored value. Nested inside the clone/fetch wall time.
555 : */
556 : virtual uint64_t take_last_refresh_ms();
557 :
558 : protected:
559 : //!< \cond DOXY_IMPL
560 : virtual bool do_is_ssh_backend_supported(git::SshBackend backend) const = 0;
561 : virtual bool do_is_ssh_backend_available(git::SshBackend backend, bool force) = 0;
562 : virtual Result do_set_ssh_backend(git::SshBackend backend) = 0;
563 : virtual Result_t<git::SshBackend> do_get_ssh_backend() const = 0;
564 :
565 : //! One probe instance for the active Git implementation (GitMngr)
566 : static GitBase &ssh_probe();
567 : //!< \endcond
568 :
569 : private:
570 : //!< \cond DOXY_IMPL
571 :
572 : using Time = std::chrono::time_point<std::chrono::steady_clock>;
573 :
574 : std::shared_ptr<git::Person> m_person;
575 : std::shared_ptr<git::Person> m_committer;
576 : std::size_t m_id = 0; //!< The id of the git repository handled
577 : bool m_debug = false; //!< Tell if debug information should be printed
578 : git::Progress m_progress; //!< The progress info
579 : ProgressCallbackBase *m_progress_callback = nullptr; //!< The progress callback
580 : std::mutex m_progress_mutex; //!< The mutex for all access to the progress data
581 : Time m_last_progress_emit{}; //!< Last ProgressCallback emit (throttle)
582 : git::FetchStep m_last_emitted_progress_step = git::FetchStep::NOT_SET;
583 : bool m_progress_emit_armed = false; //!< True after first throttled emit
584 : Time m_open_time; //!< The time when the git repo was opened
585 : Time m_last_cmd_start_time; //!< The time when the last command was started
586 : Time m_last_cmd_end_time; //!< The time when the last command was started
587 : Time m_close_time; //!< The time when the git repo was closed
588 : std::vector<std::string> m_notes_references; //!< The vector of notes references
589 : std::map<std::string, bool, std::less<>> m_map_notes_references; //!< The map of already added notes references
590 : //!< \endcond
591 : };
592 :
593 : } // namespace esys::repo
|
