githead

Common errors

• fatal: not a git repository (or any of the parent directories): .git

  cause The `githead` Python library was called in a directory that is not an initialized Git repository.
  fix Run your script from within a Git repository. If you want to create a new one, use `git init` in your desired directory, then `git add .` and `git commit -m "Initial commit"` before using `githead`.

• ModuleNotFoundError: No module named 'githead'

  cause The `githead` Python library has not been installed in the active Python environment.
  fix Install the library using pip: `pip install githead`.

• Error: Command '['git', 'rev-parse', 'HEAD']' returned non-zero exit status 128.

  cause This error typically indicates that the `git` command-line tool is not installed or not accessible in the system's PATH, or the repository is corrupted/in an uncommitted state (e.g., just `git init` without any commits).
  fix Verify that Git is installed and configured correctly on your system (`git --version`). Ensure the repository has at least one commit (`git commit -m "Initial commit"`).

Warnings

• gotcha The `githead` library requires an initialized Git repository in the current working directory or a parent directory to function correctly. If run outside a Git repository, it will raise an error (e.g., 'fatal: not a git repository').
  Fix: Ensure your Python script is executed within a directory that is part of a Git repository. You can initialize a new one with `git init` or navigate to an existing repository.
• gotcha The name 'githead' can be ambiguous, as it refers to the general Git concept of the HEAD pointer, as well as other unrelated tools like 'GitAhead' (a graphical Git client) or a Node.js CLI helper also named 'githead'. Ensure you are using the Python `githead` library (pypi.org/project/githead).
  Fix: Always import explicitly with `from githead import githead` and refer to the PyPI page or GitHub repository (github.com/Zaczero/githead) for the correct Python library.

Install

• pip install githead Install stable version

Imports

• githead
  wrong:

  import githead

  correct:

  from githead import githead

  The primary function `githead` is imported directly from the package, not the package itself.

Quickstart

This quickstart demonstrates how to import and use the `githead` function to retrieve the current Git commit hash. The example includes robust error handling for environments that may not be within an initialized Git repository, creating a temporary one for demonstration purposes.

import os
from githead import githead

def get_current_commit_hash():
    try:
        # Ensure we are in a directory that is a git repository
        # For demonstration, we'll try to create a dummy git repo if not found
        # In a real application, you'd assume a git repo or handle the error.
        
        # Check if .git directory exists in current or parent directory
        current_dir = os.getcwd()
        is_git_repo = False
        for _ in range(5): # Check up to 5 parent directories
            if os.path.exists(os.path.join(current_dir, '.git')):
                is_git_repo = True
                break
            parent_dir = os.path.dirname(current_dir)
            if parent_dir == current_dir: # Reached root
                break
            current_dir = parent_dir

        if not is_git_repo:
            # This block is for demonstration; normally, you'd expect a repo.
            # For a quickstart to run, we mock a git repo for a moment.
            print("Not in a Git repository. Initializing a temporary one for demonstration...")
            os.makedirs("temp_git_repo", exist_ok=True)
            original_cwd = os.getcwd()
            os.chdir("temp_git_repo")
            os.system("git init > /dev/null 2>&1")
            with open("test_file.txt", "w") as f:
                f.write("Hello Githead!")
            os.system("git add . > /dev/null 2>&1")
            os.system("git commit -m \"Initial commit\" > /dev/null 2>&1")
            
            commit_hash = githead()
            os.chdir(original_cwd)
            import shutil
            shutil.rmtree("temp_git_repo")
            return commit_hash
        else:
            return githead()

    except Exception as e:
        return f"Error getting commit hash: {e}"

print(f"Current Git HEAD commit hash: {get_current_commit_hash()}")