hubvault.entry.formatters

Human-readable CLI output helpers for hubvault.entry.

This module keeps git-like textual rendering logic separate from Click command registration so commands stay focused on argument parsing and public API calls. The helpers intentionally render familiar git-style summaries without pretending that hubvault has a git workspace or index.

The module contains:

short_oid() - Render a shortened object identifier
format_status_output() - Render status output
format_branch_output() - Render branch output
format_log_output() - Render log output
format_ls_tree_output() - Render ls-tree output
format_merge_output() - Render merge output
format_verify_output() - Render verify output

short_oid

hubvault.entry.formatters.short_oid(oid: str | None, length: int = 7) → str[source]

Return a shortened human-readable object identifier.

Parameters:

oid (Optional[str]) – Full object identifier, or None
length (int, optional) – Number of hexadecimal characters to keep, defaults to 7

Returns:

Short object identifier or "0" * length when oid is None

Return type:

str

Example:

>>> short_oid("abcdef1234567890abcdef1234567890abcdef12")
'abcdef1'

format_status_output

hubvault.entry.formatters.format_status_output(branch: str, head: str | None, short: bool = False, show_branch: bool = False) → str[source]

Render repository status output in a git-like style.

Parameters:

branch (str) – Branch name shown as the current CLI branch
head (Optional[str]) – Current head commit ID, if any
short (bool, optional) – Whether short-format output is requested
show_branch (bool, optional) – Whether branch information should be emitted in short mode

Returns:

Formatted status text

Return type:

str

Example:

>>> format_status_output("main", None, short=True, show_branch=True)
'## No commits on main'

format_branch_output

hubvault.entry.formatters.format_branch_output(branch_names: Sequence[str], current_branch: str, commit_map: Dict[str, GitCommitInfo | None] | None = None, verbose: bool = False) → str[source]

Render branch listings in a git-like style.

Parameters:

branch_names (Sequence[str]) – Branch names to render
current_branch (str) – Branch name marked with *
commit_map (Optional[Dict[str, Optional[GitCommitInfo]]]) – Optional mapping from branch name to newest commit entry
verbose (bool, optional) – Whether verbose listing is requested

Returns:

Formatted branch listing

Return type:

str

Example:

>>> format_branch_output(["dev", "main"], current_branch="main")
'  dev\n* main'

format_log_output

hubvault.entry.formatters.format_log_output(commits: Sequence[GitCommitInfo], oneline: bool = False) → str[source]

Render commit history in a git-like style.

Parameters:

commits (Sequence[GitCommitInfo]) – Commit entries to render
oneline (bool, optional) – Whether to use the compact one-line format

Returns:

Formatted history text

Return type:

str

Example:

>>> commit = GitCommitInfo("abcdef1234567890abcdef1234567890abcdef12", [], datetime(2024, 1, 1), "seed", "", None, None)
>>> format_log_output([commit], oneline=True)
'abcdef1 seed'

format_ls_tree_output

hubvault.entry.formatters.format_ls_tree_output(entries: Sequence[RepoFile | RepoFolder]) → str[source]

Render tree entries in a git-like ls-tree style.

Parameters:: entries (Sequence[Union[RepoFile, RepoFolder]]) – Tree entries returned by the public API
Returns:: Formatted tree listing
Return type:: str

Example:

>>> format_ls_tree_output([RepoFolder("demo", "tree123")])
'040000 tree tree123\tdemo'

format_merge_output

hubvault.entry.formatters.format_merge_output(result: MergeResult) → str[source]

Render merge results in a git-like but hubvault-aware style.

Parameters:: result (MergeResult) – Structured merge result returned by the public API
Returns:: Formatted merge text
Return type:: str

Example:

>>> formatter = format_merge_output  

format_verify_output

hubvault.entry.formatters.format_verify_output(report: VerifyReport, full: bool = False) → str[source]

Render verification results for the CLI.

Parameters:

report (VerifyReport) – Verification report returned by the public API
full (bool, optional) – Whether the report comes from full_verify()

Returns:

Formatted verification output

Return type:

str

Example:

>>> format_verify_output(VerifyReport(True), full=False)
'Quick verification OK'