VCS (Version Control System) utility functions for text evaluation. More...

Classes
class	CONTEXT_PATH_SCOPE
	RAII helper that sets the VCS context path on construction and restores the previous value on destruction. More...

Functions
void	SetContextPath (const wxString &aPath)
	Set the filesystem path used as the repository-discovery starting point for repo-scoped VCS queries (functions that would otherwise use current working directory).

wxString	GetContextPath ()
	Return the current context path for repo-scoped VCS queries.

std::string	GetCommitHash (const std::string &aPath=".", int aLength=40)
	Get the current HEAD commit identifier (hash).

std::string	GetNearestTag (const std::string &aMatch="", bool aAnyTags=false)
	Get the nearest tag/label from HEAD.

int	GetDistanceFromTag (const std::string &aMatch="", bool aAnyTags=false)
	Get the number of commits since the nearest matching tag.

bool	IsDirty (bool aIncludeUntracked=false)
	Check if the repository has uncommitted changes.

std::string	GetAuthor (const std::string &aPath=".")
	Get the author name of the HEAD commit.

std::string	GetAuthorEmail (const std::string &aPath=".")
	Get the author email of the HEAD commit.

std::string	GetCommitter (const std::string &aPath=".")
	Get the committer name of the HEAD commit.

std::string	GetCommitterEmail (const std::string &aPath=".")
	Get the committer email of the HEAD commit.

std::string	GetBranch ()
	Get the current branch name.

int64_t	GetCommitTimestamp (const std::string &aPath=".")
	Get the commit timestamp (Unix time) of the HEAD commit.

std::string	GetCommitDate (const std::string &aPath=".")
	Get the commit date of the HEAD commit as a timestamp string.

Detailed Description

VCS (Version Control System) utility functions for text evaluation.

These functions provide generic VCS operations that are currently implemented for Git repositories, but can be extended to support other VCS systems in the future.

Function Documentation

◆ GetAuthor()

std::string TEXT_EVAL_VCS::GetAuthor ( const std::string & aPath = "." )

Get the author name of the HEAD commit.

Parameters

aPath Optional file path for file-specific queries.

Returns: Author name, or empty string if not available.

Definition at line 394 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetAuthorEmail()

std::string TEXT_EVAL_VCS::GetAuthorEmail ( const std::string & aPath = "." )

Get the author email of the HEAD commit.

Parameters

aPath Optional file path for file-specific queries.

Returns: Author email, or empty string if not available.

Definition at line 400 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetBranch()

std::string TEXT_EVAL_VCS::GetBranch ( )

Get the current branch name.

Returns: Branch name (e.g., "main", "develop"), or empty string if detached or not in VCS.

Definition at line 418 of file text_eval_vcs.cpp.

References KIGIT_COMMON::GetCurrentBranchName().

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetCommitDate()

std::string TEXT_EVAL_VCS::GetCommitDate ( const std::string & aPath = "." )

Get the commit date of the HEAD commit as a timestamp string.

Parameters

aPath Optional file path for file-specific queries.

Returns: Timestamp as string (to be formatted by caller), or empty string if not available.

Definition at line 462 of file text_eval_vcs.cpp.

References GetCommitTimestamp().

◆ GetCommitHash()

std::string TEXT_EVAL_VCS::GetCommitHash	(	const std::string &	aPath = ".",
		int	aLength = 40 )

Get the current HEAD commit identifier (hash).

Parameters

aPath	Optional file path for file-specific queries. Defaults to "." for repo HEAD.
aLength	Optional hash length (4-40). Defaults to 40 for full SHA-1.

Returns: Commit hash as hex string, or empty if not in a VCS repository.

Definition at line 331 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetCommitter()

std::string TEXT_EVAL_VCS::GetCommitter ( const std::string & aPath = "." )

Get the committer name of the HEAD commit.

Parameters

aPath Optional file path for file-specific queries.

Returns: Committer name, or empty string if not available.

Definition at line 406 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetCommitterEmail()

std::string TEXT_EVAL_VCS::GetCommitterEmail ( const std::string & aPath = "." )

Get the committer email of the HEAD commit.

Parameters

aPath Optional file path for file-specific queries.

Returns: Committer email, or empty string if not available.

Definition at line 412 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetCommitTimestamp()

int64_t TEXT_EVAL_VCS::GetCommitTimestamp ( const std::string & aPath = "." )

Get the commit timestamp (Unix time) of the HEAD commit.

Parameters

aPath Optional file path for file-specific queries.

Returns: Unix timestamp in seconds, or 0 if not available.

Definition at line 433 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction(), and GetCommitDate().

◆ GetContextPath()

KICOMMON_API wxString TEXT_EVAL_VCS::GetContextPath ( )

Return the current context path for repo-scoped VCS queries.

Returns: The path previously passed to SetContextPath(), or "." if no override is active.

Definition at line 46 of file text_eval_vcs.cpp.

◆ GetDistanceFromTag()

int TEXT_EVAL_VCS::GetDistanceFromTag	(	const std::string &	aMatch = "",
		bool	aAnyTags = false )

Get the number of commits since the nearest matching tag.

Parameters

aMatch	Optional glob pattern to filter tags.
aAnyTags	If true, includes lightweight tags. If false, annotated tags only.

Returns: Distance in commits, or 0 if no tag found or at a tag.

Definition at line 361 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ GetNearestTag()

std::string TEXT_EVAL_VCS::GetNearestTag	(	const std::string &	aMatch = "",
		bool	aAnyTags = false )

Get the nearest tag/label from HEAD.

Parameters

aMatch	Optional glob pattern to filter tags. Defaults to "*" for all tags.
aAnyTags	If true, includes lightweight tags. If false, annotated tags only.

Returns: Tag name, or empty string if no matching tag found.

Definition at line 355 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ IsDirty()

bool TEXT_EVAL_VCS::IsDirty ( bool aIncludeUntracked = false )

Check if the repository has uncommitted changes.

Parameters

aIncludeUntracked If true, untracked files count as dirty. If false, only staged/modified.

Returns: true if repository is dirty, false if clean or not in a VCS repository.

Definition at line 367 of file text_eval_vcs.cpp.

Referenced by calc_parser::EVAL_VISITOR::evaluateFunction().

◆ SetContextPath()

KICOMMON_API void TEXT_EVAL_VCS::SetContextPath ( const wxString & aPath )

Set the filesystem path used as the repository-discovery starting point for repo-scoped VCS queries (functions that would otherwise use current working directory).

The context is stored per-thread. Passing an empty string clears the override, causing VCS queries to fall back to the process current working directory.

This is primarily used so non-GUI entry points (for example kicad-cli job handlers) can anchor VCS lookups to the loaded project directory without touching the process cwd.

Pass an absolute path. Relative paths are resolved by libgit2 against the process cwd, which is precisely what this override is meant to bypass.

Parameters

aPath Absolute filesystem path (directory or file inside the project), or empty to clear the override.

Definition at line 40 of file text_eval_vcs.cpp.

Referenced by SETTINGS_MANAGER::LoadProject(), and SETTINGS_MANAGER::UnloadProject().

Classes

Functions

Detailed Description

Function Documentation

◆ GetAuthor()

◆ GetAuthorEmail()

◆ GetBranch()

◆ GetCommitDate()

◆ GetCommitHash()

◆ GetCommitter()

◆ GetCommitterEmail()

◆ GetCommitTimestamp()

◆ GetContextPath()

◆ GetDistanceFromTag()

◆ GetNearestTag()

◆ IsDirty()

◆ SetContextPath()