🌜
🌞
gh-pages

gh-pages

v4.0.0

Publish to a gh-pages branch on GitHub (or any other branch on any other remote)

npm install gh-pages

README

gh-pages

Publish files to a gh-pages branch on GitHub (or any other branch anywhere else).

Getting Started

npm install gh-pages --save-dev

This module requires Git >= 1.9 and Node >= 12.

Basic Usage

var ghpages = require('gh-pages');

ghpages.publish('dist', function(err) {});

publish

ghpages.publish(dir, callback);
// or...
ghpages.publish(dir, options, callback);

Calling this function will create a temporary clone of the current repository, create a gh-pages branch if one doesn't already exist, copy over all files from the base path, or only those that match patterns from the optional src configuration, commit all changes, and push to the origin remote.

If a gh-pages branch already exists, it will be updated with all commits from the remote before adding any commits from the provided src files.

Note that any files in the gh-pages branch that are not in the src files will be removed. See the add option if you don't want any of the existing files removed.

dir

  • type: string

The base directory for all source files (those listed in the src config property).

Example use:

/**
 * Given the following directory structure:
 *
 *   dist/
 *     index.html
 *     js/
 *       site.js
 *
 * The usage below will create a `gh-pages` branch that looks like this:
 *
 *   index.html
 *   js/
 *     site.js
 *
 */
ghpages.publish('dist', callback);

Options

The default options work for simple cases. The options described below let you push to alternate branches, customize your commit messages, and more.

options.src

  • type: string|Array<string>
  • default: '**/*'

The minimatch pattern or array of patterns used to select which files should be published.

options.branch

  • type: string
  • default: 'gh-pages'
  • -b | --branch <branch name>

The name of the branch you'll be pushing to. The default uses GitHub's gh-pages branch, but this can be configured to push to any branch on any remote.

Example use of the branch option:

/**
 * This task pushes to the `master` branch of the configured `repo`.
 */
ghpages.publish('dist', {
  branch: 'master',
  repo: 'https://example.com/other/repo.git'
}, callback);

options.dest

  • type: string
  • default: '.'

The destination folder within the destination branch. By default, all files are published to the root of the repository.

Example use of the dest option:

/**
 * Place content in the static/project subdirectory of the target
 * branch.
 */
ghpages.publish('dist', {
  dest: 'static/project'
}, callback);

options.dotfiles

  • type: boolean
  • default: false

Include dotfiles. By default, files starting with . are ignored unless they are explicitly provided in the src array. If you want to also include dotfiles that otherwise match your src patterns, set dotfiles: true in your options.

Example use of the dotfiles option:

/**
 * The usage below will push dotfiles (directories and files)
 * that otherwise match the `src` pattern.
 */
ghpages.publish('dist', {dotfiles: true}, callback);

options.add

  • type: boolean
  • default: false

Only add, and never remove existing files. By default, existing files in the target branch are removed before adding the ones from your src config. If you want the task to add new src files but leave existing ones untouched, set add: true in your options.

Example use of the add option:

/**
 * The usage below will only add files to the `gh-pages` branch, never removing
 * any existing files (even if they don't exist in the `src` config).
 */
ghpages.publish('dist', {add: true}, callback);

options.repo

  • type: string
  • default: url for the origin remote of the current dir (assumes a git repository)
  • -r | --repo <repo url>

By default, gh-pages assumes that the current working directory is a git repository, and that you want to push changes to the origin remote.

If instead your script is not in a git repository, or if you want to push to another repository, you can provide the repository URL in the repo option.

Example use of the repo option:

/**
 * If the current directory is not a clone of the repository you want to work
 * with, set the URL for the repository in the `repo` option.  This usage will
 * push all files in the `src` config to the `gh-pages` branch of the `repo`.
 */
ghpages.publish('dist', {
  repo: 'https://example.com/other/repo.git'
}, callback);

options.remote

  • type: string
  • default: 'origin'

The name of the remote you'll be pushing to. The default is your 'origin' remote, but this can be configured to push to any remote.

Example use of the remote option:

/**
 * This task pushes to the `gh-pages` branch of of your `upstream` remote.
 */
ghpages.publish('dist', {
  remote: 'upstream'
}, callback);

options.tag

  • type: string
  • default: ''

Create a tag after committing changes on the target branch. By default, no tag is created. To create a tag, provide the tag name as the option value.

options.message

  • type: string
  • default: 'Updates'

The commit message for all commits.

Example use of the message option:

/**
 * This adds commits with a custom message.
 */
ghpages.publish('dist', {
  message: 'Auto-generated commit'
}, callback);

options.user

  • type: Object
  • default: null

If you are running the gh-pages task in a repository without a user.name or user.email git config properties (or on a machine without these global config properties), you must provide user info before git allows you to commit. The options.user object accepts name and email string values to identify the committer.

Example use of the user option:

ghpages.publish('dist', {
  user: {
    name: 'Joe Code',
    email: '[email protected]'
  }
}, callback);

options.remove

  • type: string
  • default: '.'

Removes files that match the given pattern (Ignored if used together with --add). By default, gh-pages removes everything inside the target branch auto-generated directory before copying the new files from dir.

Example use of the remove option:

ghpages.publish('dist', {
  remove: "*.json"
}, callback);

options.push

  • type: boolean
  • default: true

Push branch to remote. To commit only (with no push) set to false.

Example use of the push option:

ghpages.publish('dist', {push: false}, callback);

options.history

  • type: boolean
  • default: true

Push force new commit without parent history.

Example use of the history option:

ghpages.publish('dist', {history: false}, callback);

options.silent

  • type: boolean
  • default: false

Avoid showing repository URLs or other information in errors.

Example use of the silent option:

/**
 * This configuration will avoid logging the GH_TOKEN if there is an error.
 */
ghpages.publish('dist', {
  repo: 'https://' + process.env.GH_TOKEN + '@github.com/user/private-repo.git',
  silent: true
}, callback);

options.beforeAdd

  • type: function
  • default: null

Custom callback that is executed right before git add.

The CLI expects a file exporting the beforeAdd function

gh-pages --before-add ./cleanup.js

Example use of the beforeAdd option:

/**
 * beforeAdd makes most sense when `add` option is active
 * Assuming we want to keep everything on the gh-pages branch
 * but remove just `some-outdated-file.txt`
 */
ghpages.publish('dist', {
  add: true,
  async beforeAdd(git) {
    return git.rm('./some-outdated-file.txt');
  }
}, callback);

options.git

  • type: string
  • default: 'git'

Your git executable.

Example use of the git option:

/**
 * If `git` is not on your path, provide the path as shown below.
 */
ghpages.publish('dist', {
  git: '/path/to/git'
}, callback);

Command Line Utility

Installing the package creates a gh-pages command line utility. Run gh-pages --help to see a list of supported options.

With a local install of gh-pages, you can set up a package script with something like the following:

"scripts": {
  "deploy": "gh-pages -d dist"
}

And then to publish everything from your dist folder to your gh-pages branch, you'd run this:

npm run deploy

Debugging

To get additional output from the gh-pages script, set NODE_DEBUG=gh-pages. For example:

NODE_DEBUG=gh-pages npm run deploy

Dependencies

Note that this plugin requires Git 1.9 or higher (because it uses the --exit-code option for git ls-remote). If you'd like to see this working with earlier versions of Git, please open an issue.

Test Status

Tips

when get error branch already exists

{ ProcessError: fatal: A branch named 'gh-pages' already exists.

    at ChildProcess.<anonymous> (~/node_modules/gh-pages/lib/git.js:42:16)
    at ChildProcess.emit (events.js:180:13)
    at maybeClose (internal/child_process.js:936:16)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:220:5)
  code: 128,
  message: 'fatal: A branch named \'gh-pages\' already exists.\n',
  name: 'ProcessError' }

The gh-pages module writes temporary files to a node_modules/.cache/gh-pages directory. The location of this directory can be customized by setting the CACHE_DIR environment variable.

If gh-pages fails, you may find that you need to manually clean up the cache directory. To remove the cache directory, run node_modules/gh-pages/bin/gh-pages-clean or remove node_modules/.cache/gh-pages.

Deploying to github pages with custom domain

Modify the deployment line to your deploy script if you use custom domain. This will prevent the deployment from removing the domain settings in GitHub.

echo 'your_cutom_domain.online' > ./build/CNAME && gh-pages -d build"

Deploying with GitHub Actions

In order to deploy with GitHub Actions, you will need to define a user and set the git repository for the process. See the example step below

- name: Deploy with gh-pages
  run: |
    git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
    npx gh-pages -d build -u "github-actions-bot <[email protected]>"
   env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The secrets.GITHUB_TOKEN is provided automatically as part of the GitHub Action and does not require any further configuration, but simply needs to be passed in as an environmental variable to the step. GITHUB_REPOSITORY is the owner and repository name and is also passed in automatically, but does not need to be added to the env list.

See Issue #345 for more information

Deploying with GitHub Actions and a named script

If you are using a named script in the package.json file to deploy, you will need to ensure you pass the variables properly to the wrapped gh-pages script. Given the package.json script below:

"scripts": {
  "deploy": "gh-pages -d build"
}

You will need to utilize the -- option to pass any additional arguments:

- name: Deploy with gh-pages
  run: |
    git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
    npm run deploy -- -u "github-actions-bot <[email protected]>"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

See Pull Request #368 for more information.

Release Notes

4.0.0
By Tim Schaub • Published on May 10, 2022

This release doesn't include any breaking changes, but due to updated development dependencies, tests are no longer run on Node 10.

What's Changed

Full Changelog: https://github.com/tschaub/gh-pages/compare/v3.2.3...v4.0.0

3.2.3
By Tim Schaub • Published on June 21, 2021
3.0.0
By Tim Schaub • Published on May 29, 2020

Breaking changes:

None really. But tests are no longer run on Node < 10. Development dependencies were updated to address security warnings, and this meant tests could no longer be run on Node 6 or 8. If you still use these Node versions, you may still be able to use this library, but be warned that tests are no longer run on these versions.

All changes:

2.2.0
By Tim Schaub • Published on January 7, 2020
2.1.1
By Tim Schaub • Published on August 8, 2019
2.1.0
By Tim Schaub • Published on July 31, 2019
2.0.1
By Tim Schaub • Published on October 4, 2018
  • #268 - Continue even if no git configured user.
2.0.0
By Tim Schaub • Published on September 16, 2018

Breaking changes:

  • Requires Node 6 and above. If you require support for Node 4, stick with v1.2.0.
  • The git user for commits is determined by running git config user.name and git config user.email in the current working directory when gh-pages is run. Ideally, this is what you want. In v1, the git user was determined based on the gh-pages install directory. If the package was installed globally, the git user might not have been what you expected when running in a directory with a locally configured git user.

Details:

  • #264 - Better user handling (thanks @holloway for getting this going and @nuklearfiziks and @paulirish for pushing it over the edge)
  • #263 - Infra: newer syntax and upgrade deps to latest stable versions (@AviVahl)
1.2.0
By Tim Schaub • Published on June 1, 2018
1.1.0
By Tim Schaub • Published on November 17, 2017
  • #218 - Update dependencies, test on Node 8 (@tschaub)
  • #211 - Update async to the latest version 🚀 (@tschaub)
  • #202 - chore(package): update sinon to version 3.2.1 (@tschaub)
  • #201 - chore(package): update chai to version 4.1.1 (@tschaub)
  • #196 - fix(package): update fs-extra to version 4.0.1 (@tschaub)
  • #199 - Update tmp to the latest version 🚀 (@tschaub)
  • #193 - Return the promise in the publish function (@Ambyjkl)
  • #188 - chore(package): update sinon to version 2.3.3 (@tschaub)
  • #185 - fix(package): update commander to version 2.11.0 (@tschaub)
  • #186 - chore(package): update eslint to version 4.1.1 (@tschaub)
  • #187 - fix(package): update async to version 2.5.0 (@tschaub)
  • #175 - Removed unnecessary path require (@antialias)

General

License
MIT
Typescript Types
Tree-shakeable
No

Popularity

GitHub Stargazers
2,891
Community Interest
2,920
Number of Forks
184

Maintenance

Commits
10/219/22015
Last Commit
May 10, 2022
Open Issues
107
Closed Issues
75
Open Pull Requests
11
Closed Pull Requests
136

Versions

Versions Released
10/219/2201
Latest Version Released
Current Tags
latest4.0.0
beta1.0.0-beta.1

Contributors

tschaub
tschaub
Commits: 124
greenkeeperio-bot
greenkeeperio-bot
Commits: 18
greenkeeper[bot]
greenkeeper[bot]
Commits: 18
sunghwan2789
sunghwan2789
Commits: 10
markdalgleish
markdalgleish
Commits: 7
timaschew
timaschew
Commits: 4
mickelsonmichael
mickelsonmichael
Commits: 4
AviVahl
AviVahl
Commits: 3
afc163
afc163
Commits: 3
tusharmath
tusharmath
Commits: 2
okuryu
okuryu
Commits: 2
d-tsuji
d-tsuji
Commits: 1
sobolevn
sobolevn
Commits: 1
Xiphe
Xiphe
Commits: 1
Victoire44
Victoire44
Commits: 1