Utility class with helper functions for project level git operations. More...

#include <project_git_utils.h>

Static Public Member Functions
static git_repository *	GetRepositoryForFile (const char aFilename, wxString aError=nullptr, wxString *aTrustCommand=nullptr)
	Discover and open the repository that contains the given file.

static int	CreateBranch (git_repository *aRepo, const wxString &aBranchName)
	Create a new branch based on HEAD.

static wxString	GetCurrentHash (const wxString &aProjectFile, bool aShort)
	Return the current HEAD commit hash for the repository containing aProjectFile.

static git_oid	GetCapturedHeadOid (git_repository *aRepo)
	Return HEAD for commit-based text queries.

static bool	RemoveVCS (git_repository &aRepo, const wxString &aProjectPath=wxEmptyString, bool aRemoveGitDir=false, wxString aErrors=nullptr)
	Remove version control from a directory by freeing the repository and optionally removing the .git directory.

static wxString	ComputeSymlinkPreservingWorkDir (const wxString &aUserProjectPath, const wxString &aCanonicalWorkDir)
	Compute a working directory path that preserves symlinks from the user's project path.

static bool	IsWithinProjectPath (const wxString &aAbsPath, const wxString &aProjectPath)
	Test whether an absolute file path lives inside the current project directory.

static void	SafeFreeRepository (std::shared_ptr< KIGIT_COMMON > aCommon, const std::string &aLabel)
	Free the session's repository handle without pulling it out from under a running operation.

static const std::vector< wxString > &	TransientGitIgnorePatterns ()
	Shared patterns for new .gitignore files and the untracked-file filter.

static bool	IsTransientGitFile (const wxFileName &aFile)
	Match a project-relative path against the shared transient patterns.

static std::optional< wxString >	ProjectPrefix (const wxString &aWorkDir, const wxString &aProjectPath)
	The project's folder inside the repository, ending in a slash.

static bool	PathUsesGitLfs (git_repository aRepo, const wxString &aPath, const git_oid aCommit=nullptr)
	Whether git routes `aPath` through the Git LFS filter.

static bool	ProjectUsesGitLfs (const KIGIT_COMMON &aCommon, wxString aExample=nullptr, const git_oid aCommit=nullptr)
	Whether any committed file in the project's folder goes through Git LFS.

static wxString	LfsRefusal (KIGIT_COMMON *aCommon)
	Return a refusal message for LFS files or an unknown project folder, otherwise empty.

static bool	WriteBlobToFile (git_repository *aRepo, const wxString &aRef, const wxString &aPath, const wxString &aDestPath)
	Write a file as it exists at a git ref to a path on disk, so a committed version can be diffed.

static bool	WriteTreeToDir (git_repository *aRepo, const wxString &aRef, const wxString &aDestDir)
	Check out a whole tree into a directory, leaving the repository's working copy and index alone.

Detailed Description

Utility class with helper functions for project level git operations.

Definition at line 38 of file project_git_utils.h.

Member Function Documentation

◆ ComputeSymlinkPreservingWorkDir()

wxString KIGIT::PROJECT_GIT_UTILS::ComputeSymlinkPreservingWorkDir	(	const wxString &	aUserProjectPath,
		const wxString &	aCanonicalWorkDir )

static

Compute a working directory path that preserves symlinks from the user's project path.

When a project is opened via a symlinked path, git_repository_workdir() returns the canonical (symlink-resolved) path. This causes path mismatches between the tree cache (which uses the user-provided symlinked path) and the git status results (which use canonical paths). This function computes a working directory path that preserves the symlinks from the user's original project path.

Parameters

aUserProjectPath	The path the user used to open the project (may contain symlinks)
aCanonicalWorkDir	The canonical workdir from git_repository_workdir()

Returns: Working directory path with symlinks preserved, or aCanonicalWorkDir on failure

Definition at line 149 of file project_git_utils.cpp.

References KIGIT::canonicalDir().

Referenced by PROJECT::AttachGitRepository(), BOOST_AUTO_TEST_CASE(), and PROJECT_TREE_PANE::onGitInitializeProject().

◆ CreateBranch()

int KIGIT::PROJECT_GIT_UTILS::CreateBranch	(	git_repository *	aRepo,
		const wxString &	aBranchName )

static

Create a new branch based on HEAD.

Parameters

aRepo	Repository in which to create the branch.
aBranchName	Name of the new branch.

Returns: 0 on success, libgit2 error code on failure.

Definition at line 52 of file project_git_utils.cpp.

References KIGIT::BranchNameError(), GIT_BACKEND::CreateBranch(), GetGitBackend(), and git_repository.

Referenced by PROJECT_TREE_PANE::switchGitBranch().

◆ GetCapturedHeadOid()

git_oid KIGIT::PROJECT_GIT_UTILS::GetCapturedHeadOid ( git_repository * aRepo )

static

Return HEAD for commit-based text queries.

An active text-evaluation frame captures the first result per repository Git directory; later calls can return an older HEAD than the repository currently has. Without a frame, this reads the live HEAD.

Parameters

aRepo Repository to read, or nullptr.

Returns: HEAD object ID, or the zero OID when unavailable (including read errors).

Definition at line 75 of file project_git_utils.cpp.

References git_repository, and path.

Referenced by GetCurrentHash().

◆ GetCurrentHash()

wxString KIGIT::PROJECT_GIT_UTILS::GetCurrentHash	(	const wxString &	aProjectFile,
		bool	aShort )

static

Return the current HEAD commit hash for the repository containing aProjectFile.

Parameters

aProjectFile	Absolute path to any file within the repository (typically the project file path).
aShort	If true, return the short (8 char) hash, otherwise full hash.

Returns: wxString containing the hash or "no hash" if unavailable.

Definition at line 106 of file project_git_utils.cpp.

References TEXT_EVAL::ENVIRONMENT::Current(), GetCapturedHeadOid(), GetRepositoryForFile(), and TO_UTF8.

Referenced by BOOST_AUTO_TEST_CASE(), SCH_CONNECTIVITY::INPUT_STORE::ExternalSourcesChanged(), and PROJECT::TextVarResolver().

◆ GetRepositoryForFile()

git_repository * KIGIT::PROJECT_GIT_UTILS::GetRepositoryForFile	(	const char *	aFilename,
		wxString *	aError = nullptr,
		wxString *	aTrustCommand = nullptr )

static

Discover and open the repository that contains the given file.

Parameters

aFilename	Absolute path to a file inside the repository.
aError	Receives a reason worth showing when the repository cannot be opened.
aTrustCommand	Receives the git command that trusts a repository another user owns.

Returns: Newly opened git_repository or nullptr on failure.

Definition at line 40 of file project_git_utils.cpp.

References GetGitBackend(), GIT_BACKEND::GetRepositoryForFile(), and git_repository.

Referenced by PROJECT::AttachGitRepository(), and GetCurrentHash().

◆ IsTransientGitFile()

bool KIGIT::PROJECT_GIT_UTILS::IsTransientGitFile ( const wxFileName & aFile )

static

Match a project-relative path against the shared transient patterns.

Callers must keep tracked and staged files visible even when their names match.

Definition at line 493 of file project_git_utils.cpp.

Referenced by BOOST_AUTO_TEST_CASE(), and BuildGitChangeEntries().

◆ IsWithinProjectPath()

bool KIGIT::PROJECT_GIT_UTILS::IsWithinProjectPath	(	const wxString &	aAbsPath,
		const wxString &	aProjectPath )

static

Test whether an absolute file path lives inside the current project directory.

The git repository may span more than the KiCad project (the project is often a subdirectory of a larger repo). Commit and amend checklists must only offer files under the project directory, otherwise unrelated repository files leak into the commit (issue #15910). The project path is normalized to end in a separator before the prefix comparison so that a sibling such as "proj-extra/" is not treated as being inside "proj/". An empty project path matches nothing.

Parameters

aAbsPath	Absolute path of the file being tested.
aProjectPath	Absolute path of the project directory.

Returns: True if aAbsPath is within the project directory.

Definition at line 237 of file project_git_utils.cpp.

References KIGIT::canonicalDir(), and KIGIT::pathIsUnder().

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), BuildGitChangeEntries(), and ChangedTrackedFilesOutsideProject().

◆ LfsRefusal()

wxString KIGIT::PROJECT_GIT_UTILS::LfsRefusal ( KIGIT_COMMON * aCommon )

static

Return a refusal message for LFS files or an unknown project folder, otherwise empty.

The caller holds the session's action lock.

Definition at line 368 of file project_git_utils.cpp.

References _, KIGIT_COMMON::GetProjectPrefix(), KIGIT_COMMON::GetRepo(), and ProjectUsesGitLfs().

Referenced by GIT_COMMIT_PANE::doCommit(), PANEL_GIT_HISTORY::onRestoreVersion(), PANEL_GIT_STASHES::onStashSave(), and ReadGitWorktreeStatus().

◆ PathUsesGitLfs()

bool KIGIT::PROJECT_GIT_UTILS::PathUsesGitLfs	(	git_repository *	aRepo,
		const wxString &	aPath,
		const git_oid *	aCommit = nullptr )

static

Whether git routes aPath through the Git LFS filter.

aCommit reads the attributes that commit carries rather than the ones in hand, for judging a version before it is checked out.

Definition at line 293 of file project_git_utils.cpp.

References git_repository.

◆ ProjectPrefix()

std::optional< wxString > KIGIT::PROJECT_GIT_UTILS::ProjectPrefix	(	const wxString &	aWorkDir,
		const wxString &	aProjectPath )

static

The project's folder inside the repository, ending in a slash.

An empty string means the repository root. No value means either path is missing or the project is outside the repository. Uses forward slashes for libgit2.

Definition at line 278 of file project_git_utils.cpp.

References KIGIT::canonicalDir(), and KIGIT::prefixUnder().

Referenced by BOOST_AUTO_TEST_CASE(), and KIGIT_COMMON::GetProjectPrefix().

◆ ProjectUsesGitLfs()

bool KIGIT::PROJECT_GIT_UTILS::ProjectUsesGitLfs	(	const KIGIT_COMMON &	aCommon,
		wxString *	aExample = nullptr,
		const git_oid *	aCommit = nullptr )

static

Whether any committed file in the project's folder goes through Git LFS.

libgit2 runs no filter program, so every operation that writes such a file writes the placeholder text instead of the file. aExample receives the first one found.

Definition at line 390 of file project_git_utils.cpp.

References KIGIT_COMMON::GetProjectPrefix(), KIGIT_COMMON::GetRepo(), and git_repository.

Referenced by LfsRefusal(), and LIBGIT_BACKEND::PerformPull().

◆ RemoveVCS()

bool KIGIT::PROJECT_GIT_UTILS::RemoveVCS	(	git_repository *&	aRepo,
		const wxString &	aProjectPath = wxEmptyString,
		bool	aRemoveGitDir = false,
		wxString *	aErrors = nullptr )

static

Remove version control from a directory by freeing the repository and optionally removing the .git directory.

Parameters

aRepo	Repository to free (will be set to nullptr)
aProjectPath	Path to the project directory
aRemoveGitDir	If true, also remove the .git directory from disk
aErrors	Output parameter for any error messages

Returns: True on success, false on failure

Definition at line 63 of file project_git_utils.cpp.

References GetGitBackend(), git_repository, and GIT_BACKEND::RemoveVCS().

Referenced by PROJECT_TREE_PANE::WaitForGitOperations().

◆ SafeFreeRepository()

void KIGIT::PROJECT_GIT_UTILS::SafeFreeRepository	(	std::shared_ptr< KIGIT_COMMON >	aCommon,
		const std::string &	aLabel )

static

Free the session's repository handle without pulling it out from under a running operation.

With the action mutex free it goes at once, otherwise the orphan registry frees it once the running operation releases the mutex.

Parameters

aLabel Names the orphan registry entry, for shutdown diagnostics.

Definition at line 511 of file project_git_utils.cpp.

References GetGitBackend(), git_repository, GIT_BACKEND::OrphanRegistry(), and KIGIT_ORPHAN_REGISTRY::Register().

Referenced by PROJECT::ReleaseGitCommon().

◆ TransientGitIgnorePatterns()

const std::vector< wxString > & KIGIT::PROJECT_GIT_UTILS::TransientGitIgnorePatterns ( )

static

Shared patterns for new .gitignore files and the untracked-file filter.

Definition at line 428 of file project_git_utils.cpp.

Referenced by ensureProjectGitignore().

◆ WriteBlobToFile()

bool KIGIT::PROJECT_GIT_UTILS::WriteBlobToFile	(	git_repository *	aRepo,
		const wxString &	aRef,
		const wxString &	aPath,
		const wxString &	aDestPath )

static

Write a file as it exists at a git ref to a path on disk, so a committed version can be diffed.

False for an empty ref or path, or one that is not a blob.

Parameters

aRef	Branch, tag or commit to read from, for example "HEAD".
aPath	Path inside the repository, relative to its root.

Definition at line 564 of file project_git_utils.cpp.

References git_repository, and KIGIT::ResolveRefToTree().

Referenced by BOOST_AUTO_TEST_CASE(), GIT_DIFF_WORKSPACE::Materialize(), and DIALOG_GIT_MR_REVIEW::openFileDiff().

◆ WriteTreeToDir()

bool KIGIT::PROJECT_GIT_UTILS::WriteTreeToDir	(	git_repository *	aRepo,
		const wxString &	aRef,
		const wxString &	aDestDir )

static

Check out a whole tree into a directory, leaving the repository's working copy and index alone.

A hierarchical schematic needs this rather than a lone blob, because its root sheet references sub-sheet files.

Parameters

aDestDir Destination directory, created if needed.

Definition at line 607 of file project_git_utils.cpp.

References git_repository, and KIGIT::ResolveRefToTree().

Referenced by BOOST_AUTO_TEST_CASE(), BOOST_AUTO_TEST_CASE(), and GIT_DIFF_WORKSPACE::Materialize().

The documentation for this class was generated from the following files:

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ComputeSymlinkPreservingWorkDir()

◆ CreateBranch()

◆ GetCapturedHeadOid()

◆ GetCurrentHash()

◆ GetRepositoryForFile()

◆ IsTransientGitFile()

◆ IsWithinProjectPath()

◆ LfsRefusal()

◆ PathUsesGitLfs()

◆ ProjectPrefix()

◆ ProjectUsesGitLfs()

◆ RemoveVCS()

◆ SafeFreeRepository()

◆ TransientGitIgnorePatterns()

◆ WriteBlobToFile()

◆ WriteTreeToDir()