### gh-pages Package Script Example

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Demonstrates how to define a 'deploy' script in a project's package.json file to automate the gh-pages deployment process. This script executes the gh-pages command to deploy content from a specified directory.

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

--------------------------------

### Install gh-pages (npm)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Installs the gh-pages package as a development dependency using npm. This module requires Git version 1.9 or higher and Node.js version 14 or higher.

```shell
npm install gh-pages --save-dev
```

--------------------------------

### gh-pages Publish: Specify Source Directory (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Illustrates how to specify the base directory containing the files to be published. The example shows publishing files from a 'dist' directory, which will be copied to the root of the target branch.

```javascript
/**
 * 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);
```

--------------------------------

### gh-pages publish with custom git executable path

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Specify the path to the `git` executable if it is not available on the system's PATH. This is useful in environments where Git is installed in a non-standard location.

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

--------------------------------

### gh-pages Publish: Include Dotfiles (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Enables the inclusion of files and directories that start with a dot (e.g., .config). By default, dotfiles are ignored unless explicitly included in the 'src' patterns.

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

--------------------------------

### gh-pages Branch Already Exists Error

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Provides an example of a JavaScript error object encountered when the 'gh-pages' branch already exists, indicating a potential conflict during the deployment process. This error typically originates from Git operations.

```javascript
{
  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'
}
```

--------------------------------

### Executing gh-pages Deployment

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Shows the command to run a defined npm script, such as 'deploy', which in turn executes the gh-pages command to publish files to the gh-pages branch.

```shell
npm run deploy
```

--------------------------------

### Deploying with GitHub Actions

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Provides a YAML configuration snippet for a GitHub Actions workflow that deploys a site using gh-pages. It demonstrates setting the Git remote URL with a token and executing the gh-pages command with specific user information.

```yaml
- 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 <support+actions@github.com>"
   env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Deploying with Custom Domain using CNAME

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Shows how to use the `--cname` option with the gh-pages command to automatically create a CNAME file for a custom domain. This is essential for configuring custom domains on GitHub Pages.

```shell
gh-pages -d build --cname custom-domain.com
```

--------------------------------

### GitHub Actions Workflow for gh-pages Deployment

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Configures a GitHub Actions workflow to deploy using a package.json script. It demonstrates setting the Git origin URL with a token and executing the npm deploy script, passing additional arguments using the '--' operator.

```yaml
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 <support+actions@github.com>"
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Basic gh-pages Publish Usage (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Demonstrates the fundamental usage of the gh-pages module to publish files from a local directory to a Git branch. It takes the source directory as the first argument and an optional callback function.

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

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

--------------------------------

### gh-pages CLI --before-add option

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Use the `--before-add` CLI option to specify a JavaScript file that exports a `beforeAdd` function. This function runs before files are added to the commit.

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

--------------------------------

### gh-pages Publish Function Signature (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Details the two primary ways to call the publish function: with just the directory and callback, or with directory, options object, and callback. The options object allows for advanced configuration.

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

--------------------------------

### package.json Script for gh-pages Deployment

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Defines a named script in package.json to execute the gh-pages command, targeting a specific build directory.

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

--------------------------------

### gh-pages publish with beforeAdd callback

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Execute a custom asynchronous function right before `git add` is called. This callback receives the Git instance and can perform operations like removing files.

```javascript
/**
 * 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);
```

--------------------------------

### Debugging gh-pages Output

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Explains how to enable verbose debugging output for the gh-pages script by setting the NODE_DEBUG environment variable. This is useful for troubleshooting deployment issues.

```shell
NODE_DEBUG=gh-pages npm run deploy
```

--------------------------------

### gh-pages publish with user info

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Provide user name and email for Git commits when the local Git configuration is missing these properties. This is required for Git to allow commits.

```javascript
ghpages.publish('dist', {
  user: {
    name: 'Joe Code',
    email: 'coder@example.com'
  }
}, callback);
```

--------------------------------

### gh-pages Publish: Select Files with src (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Configures which files from the base directory are published using minimatch patterns. This allows for selective publishing, and the default is to publish all files ('**/*').

```javascript
ghpages.publish('dist', {
  src: ['**/*.html', 'images/*.png']
}, callback);
```

--------------------------------

### gh-pages publish to custom remote

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Configure the name of the remote repository to push to. Defaults to 'origin', but can be set to any valid remote name.

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

--------------------------------

### gh-pages Publish: Push to Alternate Branch (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Allows publishing to a branch other than the default 'gh-pages'. The 'branch' option can be set to any valid branch name, and the 'repo' option can specify an alternate Git repository URL.

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

--------------------------------

### gh-pages publish with custom repo

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Specify a custom repository URL when the current working directory is not a clone of the target repository. This allows pushing to a different repository than the one the script is run from.

```javascript
/**
 * 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);
```

--------------------------------

### gh-pages Publish: Bypass Jekyll (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Writes a `.nojekyll` file to the published branch, which is used to bypass Jekyll processing on GitHub Pages. This is useful for static sites that do not use Jekyll.

```javascript
/**
 * The usage below will add a `.nojekyll` file to the output.
 */
ghpages.publish('dist', {nojekyll: true}, callback);
```

--------------------------------

### gh-pages Publish: Set Destination Folder (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Specifies a sub-directory within the target branch where the published files should be placed. By default, files are published to the root of the repository.

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

--------------------------------

### gh-pages Publish: Custom CNAME (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Writes a `CNAME` file to the root of the published branch, allowing you to specify a custom domain name for your GitHub Pages site.

```javascript
/**
 * The usage below will add a `CNAME` file to the output.
 */
ghpages.publish('dist', {cname: 'custom-domain.com'}, callback);
```

--------------------------------

### gh-pages Cache Cleanup Command

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Illustrates the command to manually clean up the temporary cache directory used by gh-pages. This can resolve issues where the cache might be corrupted or outdated.

```shell
node_modules/gh-pages/bin/gh-pages-clean
```

--------------------------------

### gh-pages publish with file removal pattern

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Specify a glob pattern to remove files from the target branch's auto-generated directory before copying new files. Ignored if the `--add` option is used.

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

--------------------------------

### gh-pages Publish: Add Only, No Remove (JavaScript)

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Configures the publish process to only add new files and never remove existing files from the target branch. The default behavior is to remove files not present in the current source.

```javascript
/**
 * 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);
```

--------------------------------

### gh-pages publish without pushing

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Control whether the branch is pushed to the remote. Setting `push` to `false` allows committing changes without performing a push.

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

--------------------------------

### gh-pages publish with silent mode

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Enable silent mode to prevent showing repository URLs or other information in error messages. Useful for suppressing sensitive details like tokens.

```javascript
/**
 * 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);
```

--------------------------------

### gh-pages publish with custom commit message

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Set a custom commit message for all commits made during the publishing process. Defaults to 'Updates'.

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

--------------------------------

### gh-pages publish without parent history

Source: https://github.com/tschaub/gh-pages/blob/main/readme.md

Determine whether to force a new commit without parent history. Defaults to `true`, meaning history is preserved.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.