Skip to main content
The git module provides comprehensive functions for inspecting and interacting with Git repositories. All functions gracefully handle non-repository directories.
Requires git to be installed. Most functions check git::is_repo() before executing.

​
Repository state

Functions for checking repository status and state.
Check if the current directory is inside a Git repository.
git::is_repo && echo "Inside a repo"
Returns: Exit code 0 if inside a repo, 1 otherwise
Get the root directory of the current repository.
root=$(git::root_dir)
echo "Repo root: $root"
Returns: Absolute path to repository root or “unknown”
Check if there are unstaged changes in the working directory.
git::is_dirty && echo "Uncommitted changes detected"
Returns: Exit code 0 if there are unstaged changes
Check if there are staged changes ready to commit.
git::is_staged && echo "Changes staged for commit"
Returns: Exit code 0 if there are staged changes
Check if there are any stashed changes.
git::is_stashed && echo "Stash exists"
Returns: Exit code 0 if stash exists
Count the number of stashed changes.
count=$(git::stash::count)
echo "$count items in stash"
Returns: Number of stashed items (0 if none)
Count the number of staged files.
echo "$(git::staged::count) files staged"
Returns: Number of staged files
Count the number of modified but unstaged files.
echo "$(git::unstaged::count) files modified"
Returns: Number of unstaged files
Count the number of untracked files.
echo "$(git::untracked::count) untracked files"
Returns: Number of untracked files

​
Branch management

Functions for working with branches.
Get the name of the current branch.
branch=$(git::branch::current)
echo "On branch: $branch"
Returns: Current branch name or “unknown”
List all local branches.
git::branch::list
# main
# develop
# feature-x
Returns: List of local branches (one per line)
List all remote branches.
git::branch::list::remote
# origin/main
# origin/develop
Returns: List of remote branches (one per line)
List all local and remote branches.
git::branch::list::all
Returns: Combined list of all branches
Check if a local branch exists.
git::branch::exists "main" && echo "Branch exists"
Parameters:
  • branch - Branch name to check
Returns: Exit code 0 if branch exists
Check if a remote branch exists.
git::branch::exists::remote "develop" && echo "Remote branch exists"
Parameters:
  • branch - Remote branch name to check
Returns: Exit code 0 if remote branch exists

​
Commit information

Functions for inspecting commits.
Get the full commit hash.
hash=$(git::commit::hash)
echo "Current commit: $hash"

# Get hash of specific ref
prev=$(git::commit::hash "HEAD~1")
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Full 40-character commit hash
Get the short commit hash.
short=$(git::commit::short_hash)
echo "Commit: $short"
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Short commit hash (7 characters)
Get the commit message.
msg=$(git::commit::message)
echo "Last commit: $msg"
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Commit message (subject line)
Get the commit author name.
author=$(git::commit::author)
echo "Author: $author"
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Author name
Get the commit author email.
email=$(git::commit::author::email)
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Author email address
Get the commit date.
date=$(git::commit::date)
echo "Committed: $date"
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Commit date in ISO 8601 format
Get the relative commit date.
rel=$(git::commit::date::relative)
echo "Committed $rel"
# Committed 2 hours ago
Parameters:
  • ref - Git ref (default: HEAD)
Returns: Human-readable relative date
Count total commits in the current branch.
total=$(git::commit::count)
echo "$total commits"
Returns: Total number of commits
Show recent commit log.
git::log 5
# abc1234 Add feature X
# def5678 Fix bug Y
# ...
Parameters:
  • count - Number of commits to show (default: 10)
Returns: Commit log in oneline format

​
Remote repositories

Functions for working with remotes.
Check if the repository has any remotes configured.
git::has_remote && echo "Remote configured"
Returns: Exit code 0 if remotes exist
List all configured remotes.
git::remote::list
# origin
# upstream
Returns: List of remote names
Get the URL of a remote.
url=$(git::remote::url)
echo "Origin: $url"

upstream=$(git::remote::url "upstream")
Parameters:
  • remote - Remote name (default: origin)
Returns: Remote URL
Check if local branch is ahead of remote.
git::is_ahead && echo "Ready to push"
Returns: Exit code 0 if ahead
Check if local branch is behind remote.
git::is_behind && echo "Updates available"
Returns: Exit code 0 if behind
Count commits ahead of remote.
ahead=$(git::ahead_count)
echo "$ahead commits to push"
Returns: Number of commits ahead
Count commits behind remote.
behind=$(git::behind_count)
echo "$behind commits to pull"
Returns: Number of commits behind

​
Tag management

Functions for working with tags.
List all tags.
git::tag::list
# v1.0.0
# v1.1.0
# v2.0.0
Returns: List of tags
Get the most recent tag.
latest=$(git::tag::latest)
echo "Latest version: $latest"
Returns: Most recent tag or “unknown”
Check if a tag exists.
git::tag::exists "v1.0.0" && echo "Tag exists"
Parameters:
  • tag - Tag name to check
Returns: Exit code 0 if tag exists

​
Utility functions

Execute a git command with repository check.
git::exec status --short
git::exec log --oneline -5
Parameters:
  • command... - Git command and arguments
Returns: Output of git command or error if not in repo
This function checks git::is_repo() first, providing a consistent error message.

​
Usage example

source compiled.sh

if git::is_repo; then
    branch=$(git::branch::current)
    hash=$(git::commit::short_hash)
    author=$(git::commit::author)
    
    echo "Branch: $branch"
    echo "Commit: $hash by $author"
    
    if git::is_dirty; then
        echo "Warning: $(git::unstaged::count) unstaged changes"
    fi
    
    if git::is_ahead; then
        echo "$(git::ahead_count) commits ready to push"
    fi
else
    echo "Not a git repository"
fi

Build docs developers (and LLMs) love

Get started for freeTalk to us