gh-pages

Publish static sites to GitHub Pages branch

TLDR

Deploy dist folder to gh-pages

$ npx gh-pages -d [dist]

Deploy with custom message

$ npx gh-pages -d [dist] -m "[Deploy to GitHub Pages]"

Deploy to custom branch

$ npx gh-pages -d [dist] -b [docs]

Deploy specific files

$ npx gh-pages -d [dist] -s "[*.html,*.css]"

Deploy with custom remote

$ npx gh-pages -d [dist] -o [upstream]

Deploy with a custom domain (CNAME)

$ npx gh-pages -d [dist] --cname [example.com]

gh-pages is an npm package that publishes files to a GitHub Pages branch. It automates pushing built static sites to the gh-pages branch for hosting, creating clean commits of your distribution folder to the target branch.The tool makes deployment a single command and is commonly used in CI/CD pipelines and as a package.json script.

PARAMETERS

-d, --dist dir

Directory to deploy.

-s, --src pattern

File pattern within dist.

-b, --branch branch

Target branch (default: gh-pages).

-o, --remote remote

Remote name (default: origin).

-m, --message msg

Commit message.

-u, --user name

Git user name.

-e, --email email

Git user email.

-a, --add

Add files, don't remove existing.

-t, --dotfiles

Include dotfiles.

-r, --repo url

Repository URL to push to (if not in a git repo or pushing elsewhere).

--cname domain

Create a CNAME file with a custom domain name.

--nojekyll

Add .nojekyll file to bypass Jekyll processing on GitHub Pages.

CONFIGURATION

package.json

Configure a deploy script with `"deploy": "gh-pages -d dist"` in the scripts section.

CAVEATS

Requires git and npm. By default, existing files on the target branch are removed before deploying; use -a to preserve them. GitHub Pages repository settings must be configured to serve from the target branch. Use --nojekyll for sites that do not need Jekyll processing. Push credentials are required.

HISTORY

gh-pages was created by Tim Schaub to simplify GitHub Pages deployments. It became a standard tool in the JavaScript ecosystem for static site deployment.