Version Control Data Functions

These functions are designed to be used by themes.

Generic

The generic interface functions are designed to provide a level of abstraction over the type of VCS that a user might be using. By using the generic interface, a theme can provide a common look for all VCS types. See the default theme function _lp_vcs_details_color() for an example of this.

_lp_find_vcs() → var:lp_vcs_type, var:lp_vcs_root, var:lp_vcs_dir, var:lp_vcs_subtype

Returns true if the current directory is part of a version control repository. If not, returns 1. Returns the VCS type ID, subtype if one exists, the VCS data directory, and the repository root directory.

If the current directory is disabled for version control using LP_DISABLED_VCS_PATHS (checked using _lp_are_vcs_enabled()), returns 2, and the returned type is set to “disabled”.

_lp_find_vcs() will only search for VCS types that are not disabled. If all VCS types are disabled in the config, _lp_find_vcs() will return 1, as no repository will be found.

This function does a lightweight check for the existence of a version control repository, only looking for the existence of a database. It does not check if the database is valid or healthy. Use _lp_vcs_active() to test for that.

Note

lp_vcs_dir will not be set for Fossil repositories. Protect it with "${lp_vcs_dir-}".

Note

lp_vcs_subtype will not be set usually. The only currently supported subtypes are “vcsh” and “svn”, which are subtypes of “git”.

New in version 2.0.

Changed in version 2.1: Added the lp_vcs_dir and lp_vcs_subtype return values. Added support for checking the GIT_DIR environment variable.

_lp_are_vcs_enabled()

Returns true if the current directory is not excluded by the config option LP_DISABLED_VCS_PATHS.

Note

All following generic functions need _lp_find_vcs() to be run first, as they need lp_vcs_type to be set.

_lp_vcs_active()

Returns true if the detected VCS is enabled in Liquidprompt and the current directory is a valid repository of that type. This check should be done before running any other _lp_vcs_* data functions, but can be omitted for speed reasons if the checks done by _lp_find_vcs() are good enough.

New in version 2.0.

Note

Unless otherwise documented, the following functions return 0 for good data, 1 for no data, and 2 for unsupported function.

_lp_vcs_bookmark() → var:lp_vcs_bookmark

Returns true if a bookmark is active in the repository. Returns the bookmark name.

Most VCS providers do not support bookmarks.

New in version 2.0.

_lp_vcs_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

For some VCS providers, a branch is always active.

New in version 2.0.

_lp_vcs_commit_id() → var:lp_vcs_commit_id

Returns the full commit ID of the current commit. The return code is not defined.

Some VCS providers use hashes, while others use incrementing revision numbers. All VCS providers support some form of ID. The returned string should be unique enough that a user can identify the commit.

New in version 2.0.

_lp_vcs_commits_off_remote() → var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind

Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch. Returns 3 or higher if the VCS provider does not support remote tracking branches.

Returns the number of commits behind and ahead.

Most VCS providers do not support remote tracking branches.

New in version 2.0.

_lp_vcs_head_status() → var:lp_vcs_head_status, var:lp_vcs_head_details

Return true if the repo is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

Many VCS providers do not have such information. This info is unlikely to be similar across VCSs, and should probably be displayed to a user without manipulation.

Note

The details are optional, and might not be set. Protect it with "${lp_vcs_head_details-}".

New in version 2.0.

_lp_vcs_staged_files() → var:lp_vcs_staged_files

Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_staged_lines() → var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines

Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

Some VCS providers refer to stashes as “shelves”.

Some VCS providers do not support stashes.

New in version 2.0.

_lp_vcs_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

A tag will only be returned if it is a unique ID that points only to the current commit.

If multiple tags match, only one is returned. Which tag is selected is not defined.

Some VCS providers do not support unique tags.

New in version 2.0.

_lp_vcs_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

Some VCS providers refer to uncommitted files as “modified” files.

New in version 2.0.

_lp_vcs_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

Some VCS providers refer to uncommitted lines as “modified” or “changed” lines.

New in version 2.0.

_lp_vcs_unstaged_files() → var:lp_vcs_unstaged_files

Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_unstaged_lines() → var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines

Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

Many VCS providers do not support staging.

New in version 2.0.

_lp_vcs_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

Some VCS providers refer to untracked files as “extra” files.

New in version 2.0.

Bazaar

Warning

Bazaar is no longer being actively developed, and depends on Python 2, which is no longer supported. Breezy is a fork that can work with Bazaar repositories. To use Breezy in place of Bazaar, set a wrapper function:

bzr() { brz "$@"; }

Note

Bazaar does not support bookmarks. A nick is somewhat like a bookmark, but there is no command to view a naked branch name, so the nick command is used for branches.

Note

Bazaar does not support a staging area.

Note

Bazaar does not support getting details of remote tracking branches. Bazaar does not keep a local copy of the remote state, so checking this would be impossible anyway.

Note

Bazaar does not have extra head statuses. A Bazaar merge can be partially complete, but there is no command to test for it.

_lp_bzr_active()

Returns true if Bazaar is enabled in Liquidprompt and the current directory is a valid Bazaar repository. This check should be done before running any other _lp_bzr_* data functions if accessing the Bazaar data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_BZR.

New in version 2.0.

_lp_bzr_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_bzr_commit_id() → var:lp_vcs_commit_id

Returns the revision number of the current commit. The return code is not defined.

New in version 2.0.

_lp_bzr_stash_count() → var:lp_vcs_stash_count

Returns true if there are shelves the repository. Returns the number of shelves.

New in version 2.0.

_lp_bzr_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_bzr_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_bzr_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_bzr_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Fossil

Note

Fossil does not support bookmarks.

Note

Fossil does not support a staging area.

Note

Fossil does not support unique tags. Fossil tags can refer to multiple checkin IDs, so a matching tag is not a useful unique ID.

Note

Fossil does not support remote tracking branches. Fossil by default keeps the local repository in sync with the remote. Even if a user disables that, it is not possible to have a local and remote branch named the same not in sync.

_lp_fossil_active()

Returns true if Fossil is enabled in Liquidprompt and the current directory is a valid Fossil repository. This check should be done before running any other _lp_fossil_* data functions if accessing the Fossil data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_FOSSIL.

New in version 2.0.

_lp_fossil_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of “no-branch”.

_lp_fossil_commit_id() → var:lp_vcs_commit_id

Returns the full commit hash of the current commit. The return code is not defined.

New in version 2.0.

_lp_fossil_head_status() → var:lp_vcs_head_status

Return true if the repository is in a special or unusual state. Return the special status.

Does not return any extra details.

New in version 2.0.

_lp_fossil_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

New in version 2.0.

_lp_fossil_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_fossil_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_fossil_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Git

Note

Git does not support bookmarks.

_lp_git_active()

Returns true if Git is enabled in Liquidprompt and the current directory is a valid Git repository. This check should be done before running any other _lp_git_* data functions if accessing the Git data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_GIT.

New in version 2.0.

_lp_git_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of commit ID.

_lp_git_commit_id() → var:lp_vcs_commit_id

Returns the full commit hash of the current commit. The return code is not defined.

New in version 2.0.

_lp_git_commits_off_remote() → var:lp_vcs_commit_ahead, var:lp_vcs_commit_behind

Returns true if there are commits on the current branch that are not on the remote tracking branch, or commits on the remote tracking branch that are not on this branch. Returns 1 if there are no differing commits. Returns 2 if there is no matching remote tracking branch.

Returns the number of commits behind and ahead.

New in version 2.0.

_lp_git_head_status() → var:lp_vcs_head_status, var:lp_vcs_head_details

Return true if the repository is in a special or unusual state. Return the special status, and any extra details (like progress in a rebase) if applicable.

New in version 2.0.

_lp_git_staged_files() → var:lp_vcs_staged_files

Returns true if any staged files exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged files.

New in version 2.0.

_lp_git_staged_lines() → var:lp_vcs_staged_i_lines, var:lp_vcs_staged_d_lines

Returns true if any staged lines exist in the repository. In other words, tracked files that contain staged changes. Returns the number of staged lines.

New in version 2.0.

_lp_git_stash_count() → var:lp_vcs_stash_count

Returns true if there are stashes the repository. Returns the number of stashes.

New in version 2.0.

_lp_git_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_git_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_git_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_git_unstaged_files() → var:lp_vcs_unstaged_files

Returns true if any unstaged files exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged files.

New in version 2.0.

_lp_git_unstaged_lines() → var:lp_vcs_unstaged_i_lines, var:lp_vcs_unstaged_d_lines

Returns true if any unstaged lines exist in the repository. In other words, tracked files that contain unstaged changes. Returns the number of unstaged lines.

New in version 2.0.

_lp_git_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Mercurial

Note

Mercurial does not support a staging area.

Note

Mercurial remote tracking branches are disabled (see _lp_hg_commits_off_remote()).

_lp_hg_active()

Returns true if Mercurial is enabled in Liquidprompt and the current directory is a valid Mercurial repository. This check should be done before running any other _lp_hg_* data functions if accessing the Mercurial data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_HG.

New in version 2.0.

_lp_hg_bookmark() → var:lp_vcs_bookmark

Returns true if a bookmark is active in the repository. Returns the bookmark name.

Mercurial bookmarks work more like Git branches.

New in version 2.0.

_lp_hg_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

All Mercurial commits have a branch, so this function should always return true. A closer analog to Git branches are Mercurial bookmarks (see _lp_hg_bookmark()).

Changed in version 2.0: Return method changed from stdout. No branch now returns false.

_lp_hg_commit_id() → var:lp_vcs_commit_id

Returns the full global revision ID of the current commit. The return code is not defined.

New in version 2.0.

_lp_hg_commits_off_remote()

Returns 2 (disabled).

Mercurial does not keep a local copy of the remote state, so checking this will require a connection to the remote server. This means it is often prohibitively time expensive, and therefore should not be used in a prompt. See issue #217.

New in version 2.0.

_lp_hg_head_status() → var:lp_vcs_head_status

Return true if the repository is in a special or unusual state. Return the special status.

Does not return any extra details.

This function depends on _lp_find_vcs() being run first to set lp_vcs_root.

New in version 2.0.

_lp_hg_stash_count() → var:lp_vcs_stash_count

Returns true if there are shelves the repository. Returns the number of shelves.

New in version 2.0.

_lp_hg_tag() → var:lp_vcs_tag

Returns true if a tag is active in the repository. Returns the tag name.

If multiple tags match, only one is returned. Which tag is selected is not defined.

New in version 2.0.

_lp_hg_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_hg_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_hg_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.

Subversion

Note

Subversion does not support bookmarks.

Note

Subversion does not support a staging area.

Note

Subversion does not support stashes.

Note

Subversion does not have extra head statuses. A Subversion merge is no different than a manual file change, so the repository has no extra state to track.

Note

Subversion does not support remote tracking branches (as it is not a distributed version control system).

Note

Subversion does not support tags. What are generally agreed upon as being tags are internally branches. These are returned by _lp_svn_branch().

_lp_svn_active()

Returns true if Subversion is enabled in Liquidprompt and the current directory is a valid Subversion repository. This check should be done before running any other _lp_svn_* data functions if accessing the Subversion data functions directly instead of through the generic interface.

Can be disabled by LP_ENABLE_SVN.

New in version 2.0.

_lp_svn_branch() → var:lp_vcs_branch

Returns true if a branch is active in the repository. Returns the branch name.

Subversion “tags” are really branches under a “tag” directory. Tags are returned as their directory name, prefixed with “tag/”.

Changed in version 2.0: Return method changed from stdout. No branch now returns false and nothing instead of the current directory.

_lp_svn_commit_id() → var:lp_vcs_commit_id

Returns the revision number of the current commit. The return code is not defined.

New in version 2.0.

_lp_svn_uncommitted_files() → var:lp_vcs_uncommitted_files

Returns true if any uncommitted files exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted files.

New in version 2.0.

_lp_svn_uncommitted_lines() → var:lp_vcs_uncommitted_i_lines, var:lp_vcs_uncommitted_d_lines

Returns true if any uncommitted lines exist in the repository. In other words, tracked files that contain uncommitted changes. Returns the number of uncommitted lines.

New in version 2.0.

_lp_svn_untracked_files() → var:lp_vcs_untracked_files

Returns true if any untracked files exist in the repository. Returns the number of untracked files.

New in version 2.0.