git-gh-pages

Create the GitHub pages branch inside the repository in the current directory

$ git gh-pages

git-gh-pages [--branch branch-name] [--message commit-message] [--force] [--no-clean] [source-directory]

source-directory
    The local directory containing the static files to be published. This is typically the output of a static site generator's build process (e.g., build/, public/, or dist/).

--branch branch-name
    Specifies the target branch to push the content to. Defaults to gh-pages if not specified.

--message commit-message
    Provides a custom commit message for the new commit on the gh-pages branch. If omitted, a default message like 'Deploy GitHub Pages' is often used.

--force
    Forces the push to the remote branch, overwriting its history. Use with extreme caution, as it can lead to irreversible data loss on the remote branch if not used carefully.

--no-clean
    Prevents the command from deleting existing files in the target branch before copying the new content. This can be useful for partial updates or maintaining specific files.

The command git-gh-pages refers to a utility or script designed to simplify the deployment of static web content to the gh-pages branch of a Git repository, which is then served by GitHub Pages. It automates the process of taking a compiled static site (e.g., from a build/ or dist/ directory), committing it to a dedicated branch (typically gh-pages), and pushing it to the remote repository.

While not a standard command shipped with Git itself, various implementations exist as shell scripts, Node.js packages (like the gh-pages npm package), or custom build automation steps. Its primary purpose is to streamline the continuous deployment of documentation, project websites, or personal portfolios hosted on GitHub.

The exact behavior and available options of git-gh-pages can vary significantly, as it is not a universally standardized command; its functionality depends on the specific script or tool implementation being used. Implementations often require the gh-pages branch to be an 'orphan' branch (i.e., having no common history with the project's main development branch). Using the --force option should be done with great care due to the risk of data loss.

A common workflow involves:
1. Building your static site (e.g., npm run build, which outputs to dist/).
2. Running git-gh-pages with the build output directory (e.g., git-gh-pages dist/).
This process typically involves these underlying steps:
a. Switching to the gh-pages branch (or creating it if it doesn't exist and making it an orphan branch).
b. Copying the contents of the source-directory to the root of the gh-pages branch, often after clearing existing contents.
c. Staging and committing these new changes.
d. Pushing the gh-pages branch to the remote repository (e.g., origin gh-pages).
e. Switching back to the original development branch (e.g., main).

The concept of git-gh-pages emerged with the popularity of GitHub Pages, a feature introduced by GitHub to host static websites directly from a repository's gh-pages branch. As static site generators (like Jekyll, Hugo, Eleventy) and client-side web development grew, automating the deployment process became crucial. Early users often relied on manual Git commands or custom shell scripts. Over time, community-driven tools and npm packages (e.g., gh-pages) were developed to encapsulate this common workflow, making it easier for developers to publish their sites without complex CI/CD setups.

git(1), git-checkout(1), git-push(1), git-subtree(1)