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 for repository discovery and relative file queries.

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

bool	GetContextIsFile ()
	File/directory classification captured when the current context was activated.

static std::string	ReadCommitHash (const std::string &aPath)

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.

static bool	ReadIsDirty (bool aIncludeUntracked)

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.

static std::string	ReadBranch ()

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

static int64_t	ReadCommitTimestamp (const std::string &aPath)

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.

TEXT_EVAL::ENVIRONMENT::VCS_VALUE	ReadSource (const TEXT_EVAL::ENVIRONMENT::VCS_KEY &aKey)
	Re-read an owned query descriptor using any active frame memo.

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. File paths may be absolute or relative to the context directory (the parent directory when the context names an existing file at activation). Without a context, relative paths use the cwd.

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 500 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 506 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 539 of file text_eval_vcs.cpp.

References ReadBranch(), and text.

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 582 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 446 of file text_eval_vcs.cpp.

References ReadCommitHash().

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 512 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 518 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 575 of file text_eval_vcs.cpp.

References ReadCommitTimestamp().

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

◆ GetContextIsFile()

KICOMMON_API bool TEXT_EVAL_VCS::GetContextIsFile ( )

File/directory classification captured when the current context was activated.

Definition at line 58 of file text_eval_vcs.cpp.

Referenced by BOOST_AUTO_TEST_CASE().

◆ 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 52 of file text_eval_vcs.cpp.

Referenced by BOOST_AUTO_TEST_CASE().

◆ 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 460 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 454 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 493 of file text_eval_vcs.cpp.

References ReadIsDirty().

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

◆ ReadBranch()

static std::string TEXT_EVAL_VCS::ReadBranch ( )

static

Definition at line 524 of file text_eval_vcs.cpp.

References KIGIT_COMMON::GetCurrentBranchName().

Referenced by GetBranch(), and ReadSource().

◆ ReadCommitHash()

static std::string TEXT_EVAL_VCS::ReadCommitHash ( const std::string & aPath )

static

Definition at line 423 of file text_eval_vcs.cpp.

Referenced by GetCommitHash(), and ReadSource().

◆ ReadCommitTimestamp()

static int64_t TEXT_EVAL_VCS::ReadCommitTimestamp ( const std::string & aPath )

static

Definition at line 546 of file text_eval_vcs.cpp.

Referenced by GetCommitTimestamp(), and ReadSource().

◆ ReadIsDirty()

static bool TEXT_EVAL_VCS::ReadIsDirty ( bool aIncludeUntracked )

static

Definition at line 466 of file text_eval_vcs.cpp.

Referenced by IsDirty(), and ReadSource().

◆ ReadSource()

KICOMMON_API TEXT_EVAL::ENVIRONMENT::VCS_VALUE TEXT_EVAL_VCS::ReadSource ( const TEXT_EVAL::ENVIRONMENT::VCS_KEY & aKey )

Re-read an owned query descriptor using any active frame memo.

Run source comparison outside SOURCE_SCOPE collection: replay records consultations too.

Definition at line 589 of file text_eval_vcs.cpp.

References TEXT_EVAL::ENVIRONMENT::Current(), GetGitBackend(), path, ReadBranch(), ReadCommitHash(), ReadCommitTimestamp(), and ReadIsDirty().

Referenced by BOOST_AUTO_TEST_CASE().

◆ SetContextPath()

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

Set the filesystem path used for repository discovery and relative file queries.

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.

Prefer an absolute path. Relative contexts use the process cwd. Whether the path names an existing file is captured here; later removal does not change its directory interpretation.

Parameters

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

Definition at line 44 of file text_eval_vcs.cpp.

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

Classes

Functions

Detailed Description

Function Documentation

◆ GetAuthor()

◆ GetAuthorEmail()

◆ GetBranch()

◆ GetCommitDate()

◆ GetCommitHash()

◆ GetCommitter()

◆ GetCommitterEmail()

◆ GetCommitTimestamp()

◆ GetContextIsFile()

◆ GetContextPath()

◆ GetDistanceFromTag()

◆ GetNearestTag()

◆ IsDirty()

◆ ReadBranch()

◆ ReadCommitHash()

◆ ReadCommitTimestamp()

◆ ReadIsDirty()

◆ ReadSource()

◆ SetContextPath()