Publish files to a {\ttfamily gh-\/pages} branch on Git\+Hub (or any other branch anywhere else).\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11307}{}\doxysection{Getting Started}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11307}

\begin{DoxyCode}{0}
\DoxyCodeLine{npm install gh-\/pages -\/-\/save-\/dev }

\end{DoxyCode}


This module requires Git {\ttfamily $>$=1.\+9}.\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11308}{}\doxysection{Basic Usage}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11308}

\begin{DoxyCode}{0}
\DoxyCodeLine{var ghpages = require('gh-\/pages');}
\DoxyCodeLine{}
\DoxyCodeLine{ghpages.publish('dist', function(err) \{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11309}{}\doxysection{$<$tt$>$publish$<$/tt$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11309}

\begin{DoxyCode}{0}
\DoxyCodeLine{ghpages.publish(dir, callback);}
\DoxyCodeLine{// or...}
\DoxyCodeLine{ghpages.publish(dir, options, callback); }

\end{DoxyCode}


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

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

{\bfseries{Note}} that any files in the {\ttfamily gh-\/pages} branch that are {\itshape not} in the {\ttfamily src} files {\bfseries{will be removed}}. See the \href{\#optionsadd}{\texttt{ {\ttfamily add} option}} if you don\textquotesingle{}t want any of the existing files removed.\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11310}{}\doxysubsection{$<$a id=\char`\"{}dir\char`\"{}$>$$<$tt$>$dir$<$/tt$>$$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11310}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\end{DoxyItemize}

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

Example use\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11311}{}\doxysubsection{Options}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11311}
The default options work for simple cases. The options described below let you push to alternate branches, customize your commit messages, and more.\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11312}{}\doxysubsubsection{$<$a id=\char`\"{}optionssrc\char`\"{}$>$options.\+src$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11312}

\begin{DoxyItemize}
\item type\+: {\ttfamily string$\vert$\+Array$<$string$>$}
\item default\+: `'$\ast$$\ast$/$\ast$\textquotesingle{}\`{}
\end{DoxyItemize}

The \href{https://github.com/isaacs/minimatch}{\texttt{ minimatch}} pattern or array of patterns used to select which files should be published.\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11313}{}\doxysubsubsection{$<$a id=\char`\"{}optionsbranch\char`\"{}$>$options.\+branch$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11313}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `\textquotesingle{}gh-\/pages'\`{}
\end{DoxyItemize}

The name of the branch you\textquotesingle{}ll be pushing to. The default uses Git\+Hub\textquotesingle{}s {\ttfamily gh-\/pages} branch, but this can be configured to push to any branch on any remote.

Example use of the {\ttfamily branch} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11314}{}\doxysubsubsection{$<$a id=\char`\"{}optionsdest\char`\"{}$>$options.\+dest$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11314}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `'.\textquotesingle{}\`{}
\end{DoxyItemize}

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

Example use of the {\ttfamily dest} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11315}{}\doxysubsubsection{$<$a id=\char`\"{}optionsdotfiles\char`\"{}$>$options.\+dotfiles$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11315}

\begin{DoxyItemize}
\item type\+: {\ttfamily boolean}
\item default\+: {\ttfamily false}
\end{DoxyItemize}

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

Example use of the {\ttfamily dotfiles} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11316}{}\doxysubsubsection{$<$a id=\char`\"{}optionsadd\char`\"{}$>$options.\+add$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11316}

\begin{DoxyItemize}
\item type\+: {\ttfamily boolean}
\item default\+: {\ttfamily false}
\end{DoxyItemize}

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

Example use of the {\ttfamily add} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11317}{}\doxysubsubsection{$<$a id=\char`\"{}optionsrepo\char`\"{}$>$options.\+repo$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11317}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: url for the origin remote of the current dir (assumes a git repository)
\end{DoxyItemize}

By default, {\ttfamily gh-\/pages} assumes that the current working directory is a git repository, and that you want to push changes to the {\ttfamily 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 {\ttfamily repo} option.

Example use of the {\ttfamily repo} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11318}{}\doxysubsubsection{$<$a id=\char`\"{}optionsremote\char`\"{}$>$options.\+remote$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11318}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `\textquotesingle{}origin'\`{}
\end{DoxyItemize}

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

Example use of the {\ttfamily remote} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11319}{}\doxysubsubsection{$<$a id=\char`\"{}optionstag\char`\"{}$>$options.\+tag$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11319}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `'\textquotesingle{}\`{}
\end{DoxyItemize}

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.\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11320}{}\doxysubsubsection{$<$a id=\char`\"{}optionsmessage\char`\"{}$>$options.\+message$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11320}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `\textquotesingle{}Updates'\`{}
\end{DoxyItemize}

The commit message for all commits.

Example use of the {\ttfamily message} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11321}{}\doxysubsubsection{$<$a id=\char`\"{}optionsuser\char`\"{}$>$options.\+user$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11321}

\begin{DoxyItemize}
\item type\+: {\ttfamily Object}
\item default\+: {\ttfamily null}
\end{DoxyItemize}

If you are running the {\ttfamily gh-\/pages} task in a repository without a {\ttfamily user.\+name} or {\ttfamily 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 {\ttfamily options.\+user} object accepts {\ttfamily name} and {\ttfamily email} string values to identify the committer.

Example use of the {\ttfamily user} option\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{ghpages.publish('dist', \{}
\DoxyCodeLine{  user: \{}
\DoxyCodeLine{    name: 'Joe Code',}
\DoxyCodeLine{    email: 'coder@example.com'}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\}, callback); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11322}{}\doxysubsubsection{$<$a id=\char`\"{}optionsuser\char`\"{}$>$options.\+remove$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11322}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `'.\textquotesingle{}\`{}
\end{DoxyItemize}

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

Example use of the {\ttfamily remove} option\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{ghpages.publish('dist', \{}
\DoxyCodeLine{  remove: "{}*.json"{}}
\DoxyCodeLine{\}, callback); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11323}{}\doxysubsubsection{$<$a id=\char`\"{}optionspush\char`\"{}$>$options.\+push$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11323}

\begin{DoxyItemize}
\item type\+: {\ttfamily boolean}
\item default\+: {\ttfamily true}
\end{DoxyItemize}

Push branch to remote. To commit only (with no push) set to {\ttfamily false}.

Example use of the {\ttfamily push} option\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{ghpages.publish('dist', \{push: false\}, callback); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11324}{}\doxysubsubsection{$<$a id=\char`\"{}optionshistory\char`\"{}$>$options.\+history$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11324}

\begin{DoxyItemize}
\item type\+: {\ttfamily boolean}
\item default\+: {\ttfamily true}
\end{DoxyItemize}

Push force new commit without parent history.

Example use of the {\ttfamily history} option\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{ghpages.publish('dist', \{history: false\}, callback); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11325}{}\doxysubsubsection{$<$a id=\char`\"{}optionssilent\char`\"{}$>$options.\+silent$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11325}

\begin{DoxyItemize}
\item type\+: {\ttfamily boolean}
\item default\+: {\ttfamily false}
\end{DoxyItemize}

Avoid showing repository URLs or other information in errors.

Example use of the {\ttfamily silent} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11326}{}\doxysubsubsection{$<$a id=\char`\"{}optionsgit\char`\"{}$>$options.\+git$<$/a$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11326}

\begin{DoxyItemize}
\item type\+: {\ttfamily string}
\item default\+: `\textquotesingle{}git'\`{}
\end{DoxyItemize}

Your {\ttfamily git} executable.

Example use of the {\ttfamily git} option\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11327}{}\doxysection{Command Line Utility}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11327}
Installing the package creates a {\ttfamily gh-\/pages} command line utility. Run {\ttfamily gh-\/pages -\/-\/help} to see a list of supported options.

With a local install of {\ttfamily gh-\/pages}, you can set up a package script with something like the following\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{"{}scripts"{}: \{}
\DoxyCodeLine{  "{}deploy"{}: "{}gh-\/pages -\/d dist"{}}
\DoxyCodeLine{\} }

\end{DoxyCode}


And then to publish everything from your {\ttfamily dist} folder to your {\ttfamily gh-\/pages} branch, you\textquotesingle{}d run this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{npm run deploy }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11328}{}\doxysection{Debugging}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11328}
To get additional output from the {\ttfamily gh-\/pages} script, set {\ttfamily NODE\+\_\+\+DEBUG=gh-\/pages}. For example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{NODE\_DEBUG=gh-\/pages npm run deploy }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11329}{}\doxysection{Dependencies}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11329}
Note that this plugin requires Git 1.\+9 or higher (because it uses the {\ttfamily -\/-\/exit-\/code} option for {\ttfamily git ls-\/remote}). If you\textquotesingle{}d like to see this working with earlier versions of Git, please \href{https://github.com/tschaub/gh-pages/issues}{\texttt{ open an issue}}.

\href{https://travis-ci.org/tschaub/gh-pages}{\texttt{ }}\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11330}{}\doxysection{Tips}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11330}
\hypertarget{md_sfcode_node_modules_gh_pages_readme_autotoc_md11331}{}\doxysubsection{when get error $<$tt$>$branch already exists$<$/tt$>$}\label{md_sfcode_node_modules_gh_pages_readme_autotoc_md11331}

\begin{DoxyCode}{0}
\DoxyCodeLine{\{ ProcessError: fatal: A branch named 'gh-\/pages' already exists.}
\DoxyCodeLine{}
\DoxyCodeLine{    at ChildProcess.<anonymous> (\string~/node\_modules/gh-\/pages/lib/git.js:42:16)}
\DoxyCodeLine{    at ChildProcess.emit (events.js:180:13)}
\DoxyCodeLine{    at maybeClose (internal/child\_process.js:936:16)}
\DoxyCodeLine{    at Process.ChildProcess.\_handle.onexit (internal/child\_process.js:220:5)}
\DoxyCodeLine{  code: 128,}
\DoxyCodeLine{  message: 'fatal: A branch named \(\backslash\)'gh-\/pages\(\backslash\)' already exists.\(\backslash\)n',}
\DoxyCodeLine{  name: 'ProcessError' \}}

\end{DoxyCode}


When processing {\ttfamily gh-\/pages} module generate file in$<$tt$>$.\+cache/ and if stuck some reason like wrong password it will not automatically cleanup

Run {\ttfamily $\sim$node\+\_\+modules/gh-\/pages/bin/gh-\/pages-\/clean} or remove {\ttfamily $\sim$node\+\_\+modules/gh-\/pages/.cache} 