GitHub Pages Import

Common errors

• ghp-import: command not found

  cause The `ghp-import` executable is not found in your system's PATH, typically because the package was not installed or its installation directory is not properly configured in your environment variables.
  fix Ensure `ghp-import` is installed using `pip install ghp-import`. If already installed, verify your system's PATH includes the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in Python installation on Windows).

• ImportError: cannot import name main

  cause This error typically occurs with older versions of `ghp-import` or when there's a conflict in the Python environment, where the entry point `main` cannot be imported from the `ghp_import` module.
  fix Upgrade `ghp-import` to the latest version using `pip install --upgrade ghp-import` to ensure you have the most compatible and current module structure.

• ERROR: Permission to <username>/<repository>.git denied to <user>. fatal: Could not read from remote repository.

  cause This error indicates that your Git client lacks the necessary authentication or authorization to push changes to the GitHub repository. This is usually due to incorrect SSH keys, expired Personal Access Tokens (PATs), or insufficient repository permissions.
  fix Verify your GitHub access rights. For SSH, ensure your SSH key is correctly added to your GitHub account and your SSH agent is running. For HTTPS, update your Git credentials with a valid Personal Access Token that has repository write access.

• fatal: A branch named 'gh-pages' already exists

  cause This Git error occurs when `ghp-import` attempts to create or manage the `gh-pages` branch, but a local reference to that branch already exists in your Git repository, possibly from a previous interrupted deployment or a corrupted local cache.
  fix First, try removing the local `gh-pages` branch with `git branch -D gh-pages`. If this doesn't resolve it, especially after an interrupted `gh-pages` deployment, manually clear the local cache used by deployment tools (e.g., for `gh-pages` npm package, it might be `rm -rf node_modules/.cache/gh-pages`). After cleaning, retry the `ghp-import` command.

Warnings

• breaking ghp-import will DESTROY your `gh-pages` branch. It assumes that the `gh-pages` branch is 100% derivative of your source files. Any manual edits made directly on the `gh-pages` branch will be lost upon execution.
  Fix: Always treat your `gh-pages` branch as entirely generated by ghp-import. Do not make manual edits directly on this branch. If you need to include static assets not generated by your build process, place them within your source directory and ensure your build process copies them, or manage them in your main branch and let ghp-import handle the entire `gh-pages` content. Consider using the `-o` or `--no-history` option to discard previous history and keep the repository size down.
• gotcha By default, ghp-import pushes to the `gh-pages` branch. For GitHub User or Organization Pages (e.g., `username.github.io` or `orgname.github.io`), the content is served from the `master` (or `main`) branch. Pushing to `gh-pages` in this scenario will not publish your site.
  Fix: For User/Organization Pages, use the `-b` or `--branch` flag to specify the correct branch, typically `master` or `main`. Example: `ghp-import -n -p -f _build/html -b master`.
• gotcha If your static site generator already produces complete HTML, GitHub Pages' default Jekyll processing can interfere. This might lead to unexpected rendering issues or files not being served correctly.
  Fix: Always include the `-n` or `--no-jekyll` flag when running `ghp-import` if your content is pre-built HTML. This tells GitHub Pages not to process your site with Jekyll, ensuring your content is served as-is.
• deprecated Before version 1.0.0, programmatic usage of ghp-import was less straightforward and sometimes involved vendoring or modifying the script. Directly importing `ghp_import` as a Python function with keyword arguments was fully supported from version 1.0.0.
  Fix: Update to ghp-import version 1.0.0 or later to use the `from ghp_import import ghp_import` pattern for programmatic deployment, which offers clearer API and better maintainability.
• breaking Attempting to run `ghp-import` directly as a shell command within a Python script (e.g., `ghp-import -n -p -f docs_output`) will result in a `SyntaxError`. Python does not execute shell commands directly; they must be run via the `subprocess` module or by importing and calling the library's Python API.
  Fix: To execute `ghp-import` from a Python script, you must either use the `subprocess` module (e.g., `import subprocess; subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`) or, if you intend to use the programmatic interface, import and call the library's Python API correctly (e.g., `from ghp_import import ghp_import; ghp_import.ghp_import(no_jekyll=True, push=True, doc_root='docs_output')`).
• gotcha Attempting to run `ghp-import` shell commands directly within a Python script will result in a `SyntaxError`. ghp-import is designed as a command-line tool. To execute it from a Python script, you must use the `subprocess` module (e.g., `subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`) or, if supported, import it programmatically (e.g., `from ghp_import import ghp_import`).
  Fix: To execute `ghp-import` as a command-line tool from Python, use `subprocess.run()` (e.g., `import subprocess; subprocess.run(['ghp-import', '-n', '-p', '-f', 'docs_output'])`). For programmatic access, ensure you are importing the library directly, as described in Warning 3 (e.g., `from ghp_import import ghp_import`).

Install

• pip install ghp-import Install with pip

Imports

• ghp_import

  from ghp_import import ghp_import

  This is for programmatic use; the library is primarily a command-line tool.

Quickstart

The most common way to use ghp-import is as a command-line tool, pointing it to your generated static files. The example shows how to deploy a 'docs_output' directory to the 'gh-pages' branch, automatically add a '.nojekyll' file (to prevent Jekyll processing), and push to the remote. It also includes a Python programmatic example for more advanced integration.

# Using as a command-line tool (recommended for typical use cases)
# Assuming your built documentation is in a 'docs_output' directory
# This command will create/update the gh-pages branch, add a .nojekyll file, and push.
ghp-import -n -p -f docs_output

# Using programmatically (if you need to integrate into a Python script)
from ghp_import import ghp_import

# Example: deploy 'build' directory, push to origin, include .nojekyll
ghp_import('build', push=True, nojekyll=True, mesg='Update GitHub Pages via script')