1 |
|
2 | # gh-pages
|
3 |
|
4 | Publish files to a `gh-pages` branch on GitHub (or any other branch anywhere else).
|
5 |
|
6 | ## Getting Started
|
7 |
|
8 | ```shell
|
9 | npm install gh-pages --save-dev
|
10 | ```
|
11 |
|
12 | This module requires Git `>=1.9`.
|
13 |
|
14 | ## Basic Usage
|
15 |
|
16 | ```js
|
17 | var ghpages = require('gh-pages');
|
18 |
|
19 | ghpages.publish('dist', function(err) {});
|
20 | ```
|
21 |
|
22 |
|
23 | ## `publish`
|
24 |
|
25 | ```js
|
26 | ghpages.publish(dir, callback);
|
27 | // or...
|
28 | ghpages.publish(dir, options, callback);
|
29 | ```
|
30 |
|
31 | 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.
|
32 |
|
33 | 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.
|
34 |
|
35 | **Note** that any files in the `gh-pages` branch that are *not* in the `src` files **will be removed**. See the [`add` option](#optionsadd) if you don't want any of the existing files removed.
|
36 |
|
37 |
|
38 | ### <a id="dir">`dir`</a>
|
39 | * type: `string`
|
40 |
|
41 | The base directory for all source files (those listed in the `src` config property).
|
42 |
|
43 | Example use:
|
44 |
|
45 | ```js
|
46 | /**
|
47 | * Given the following directory structure:
|
48 | *
|
49 | * dist/
|
50 | * index.html
|
51 | * js/
|
52 | * site.js
|
53 | *
|
54 | * The usage below will create a `gh-pages` branch that looks like this:
|
55 | *
|
56 | * index.html
|
57 | * js/
|
58 | * site.js
|
59 | *
|
60 | */
|
61 | ghpages.publish('dist', callback);
|
62 | ```
|
63 |
|
64 |
|
65 | ### Options
|
66 |
|
67 | The default options work for simple cases. The options described below let you push to alternate branches, customize your commit messages, and more.
|
68 |
|
69 |
|
70 | #### <a id="optionssrc">options.src</a>
|
71 | * type: `string|Array<string>`
|
72 | * default: `'**/*'`
|
73 |
|
74 | The [minimatch](https://github.com/isaacs/minimatch) pattern or array of patterns used to select which files should be published.
|
75 |
|
76 |
|
77 | #### <a id="optionsbranch">options.branch</a>
|
78 | * type: `string`
|
79 | * default: `'gh-pages'`
|
80 |
|
81 | 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.
|
82 |
|
83 | Example use of the `branch` option:
|
84 |
|
85 | ```js
|
86 | /**
|
87 | * This task pushes to the `master` branch of the configured `repo`.
|
88 | */
|
89 | ghpages.publish('dist', {
|
90 | branch: 'master',
|
91 | repo: 'https://example.com/other/repo.git'
|
92 | }, callback);
|
93 | ```
|
94 |
|
95 |
|
96 | #### <a id="optionsdest">options.dest</a>
|
97 | * type: `string`
|
98 | * default: `'.'`
|
99 |
|
100 | The destination folder within the destination branch. By default, all files are published to the root of the repository.
|
101 |
|
102 | Example use of the `dest` option:
|
103 |
|
104 | ```js
|
105 | /**
|
106 | * Place content in the static/project subdirectory of the target
|
107 | * branch.
|
108 | */
|
109 | ghpages.publish('dist', {
|
110 | dest: 'static/project'
|
111 | }, callback);
|
112 | ```
|
113 |
|
114 | #### <a id="optionsdotfiles">options.dotfiles</a>
|
115 | * type: `boolean`
|
116 | * default: `false`
|
117 |
|
118 | 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.
|
119 |
|
120 | Example use of the `dotfiles` option:
|
121 |
|
122 | ```js
|
123 | /**
|
124 | * The usage below will push dotfiles (directories and files)
|
125 | * that otherwise match the `src` pattern.
|
126 | */
|
127 | ghpages.publish('dist', {dotfiles: true}, callback);
|
128 | ```
|
129 |
|
130 |
|
131 | #### <a id="optionsadd">options.add</a>
|
132 | * type: `boolean`
|
133 | * default: `false`
|
134 |
|
135 | 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.
|
136 |
|
137 | Example use of the `add` option:
|
138 |
|
139 | ```js
|
140 | /**
|
141 | * The usage below will only add files to the `gh-pages` branch, never removing
|
142 | * any existing files (even if they don't exist in the `src` config).
|
143 | */
|
144 | ghpages.publish('dist', {add: true}, callback);
|
145 | ```
|
146 |
|
147 |
|
148 | #### <a id="optionsrepo">options.repo</a>
|
149 | * type: `string`
|
150 | * default: url for the origin remote of the current dir (assumes a git repository)
|
151 |
|
152 | 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.
|
153 |
|
154 | 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.
|
155 |
|
156 | Example use of the `repo` option:
|
157 |
|
158 | ```js
|
159 | /**
|
160 | * If the current directory is not a clone of the repository you want to work
|
161 | * with, set the URL for the repository in the `repo` option. This usage will
|
162 | * push all files in the `src` config to the `gh-pages` branch of the `repo`.
|
163 | */
|
164 | ghpages.publish('dist', {
|
165 | repo: 'https://example.com/other/repo.git'
|
166 | }, callback);
|
167 | ```
|
168 |
|
169 |
|
170 | #### <a id="optionsremote">options.remote</a>
|
171 | * type: `string`
|
172 | * default: `'origin'`
|
173 |
|
174 | 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.
|
175 |
|
176 | Example use of the `remote` option:
|
177 |
|
178 | ```js
|
179 | /**
|
180 | * This task pushes to the `gh-pages` branch of of your `upstream` remote.
|
181 | */
|
182 | ghpages.publish('dist', {
|
183 | remote: 'upstream'
|
184 | }, callback);
|
185 | ```
|
186 |
|
187 |
|
188 | #### <a id="optionstag">options.tag</a>
|
189 | * type: `string`
|
190 | * default: `''`
|
191 |
|
192 | 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.
|
193 |
|
194 |
|
195 | #### <a id="optionsmessage">options.message</a>
|
196 | * type: `string`
|
197 | * default: `'Updates'`
|
198 |
|
199 | The commit message for all commits.
|
200 |
|
201 | Example use of the `message` option:
|
202 |
|
203 | ```js
|
204 | /**
|
205 | * This adds commits with a custom message.
|
206 | */
|
207 | ghpages.publish('dist', {
|
208 | message: 'Auto-generated commit'
|
209 | }, callback);
|
210 | ```
|
211 |
|
212 |
|
213 | #### <a id="optionsuser">options.user</a>
|
214 | * type: `Object`
|
215 | * default: `null`
|
216 |
|
217 | 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.
|
218 |
|
219 | Example use of the `user` option:
|
220 |
|
221 | ```js
|
222 | ghpages.publish('dist', {
|
223 | user: {
|
224 | name: 'Joe Code',
|
225 | email: 'coder@example.com'
|
226 | }
|
227 | }, callback);
|
228 | ```
|
229 |
|
230 | #### <a id="optionsuser">options.remove</a>
|
231 | * type: `string`
|
232 | * default: `'.'`
|
233 |
|
234 | Removes files that match the given pattern (Ignored if used together with
|
235 | `--add`). By default, `gh-pages` removes everything inside the target branch
|
236 | auto-generated directory before copying the new files from `dir`.
|
237 |
|
238 | Example use of the `remove` option:
|
239 |
|
240 | ```js
|
241 | ghpages.publish('dist', {
|
242 | remove: "*.json"
|
243 | }, callback);
|
244 | ```
|
245 |
|
246 |
|
247 | #### <a id="optionspush">options.push</a>
|
248 | * type: `boolean`
|
249 | * default: `true`
|
250 |
|
251 | Push branch to remote. To commit only (with no push) set to `false`.
|
252 |
|
253 | Example use of the `push` option:
|
254 |
|
255 | ```js
|
256 | ghpages.publish('dist', {push: false}, callback);
|
257 | ```
|
258 |
|
259 |
|
260 | #### <a id="optionshistory">options.history</a>
|
261 | * type: `boolean`
|
262 | * default: `true`
|
263 |
|
264 | Push force new commit without parent history.
|
265 |
|
266 | Example use of the `history` option:
|
267 |
|
268 | ```js
|
269 | ghpages.publish('dist', {history: false}, callback);
|
270 | ```
|
271 |
|
272 |
|
273 | #### <a id="optionssilent">options.silent</a>
|
274 | * type: `boolean`
|
275 | * default: `false`
|
276 |
|
277 | Avoid showing repository URLs or other information in errors.
|
278 |
|
279 | Example use of the `silent` option:
|
280 |
|
281 | ```js
|
282 | /**
|
283 | * This configuration will avoid logging the GH_TOKEN if there is an error.
|
284 | */
|
285 | ghpages.publish('dist', {
|
286 | repo: 'https://' + process.env.GH_TOKEN + '@github.com/user/private-repo.git',
|
287 | silent: true
|
288 | }, callback);
|
289 | ```
|
290 |
|
291 |
|
292 | #### <a id="optionsgit">options.git</a>
|
293 | * type: `string`
|
294 | * default: `'git'`
|
295 |
|
296 | Your `git` executable.
|
297 |
|
298 | Example use of the `git` option:
|
299 |
|
300 | ```js
|
301 | /**
|
302 | * If `git` is not on your path, provide the path as shown below.
|
303 | */
|
304 | ghpages.publish('dist', {
|
305 | git: '/path/to/git'
|
306 | }, callback);
|
307 | ```
|
308 |
|
309 | ## Command Line Utility
|
310 |
|
311 | Installing the package creates a `gh-pages` command line utility. Run `gh-pages --help` to see a list of supported options.
|
312 |
|
313 | With a local install of `gh-pages`, you can set up a package script with something like the following:
|
314 |
|
315 | ```shell
|
316 | "scripts": {
|
317 | "deploy": "gh-pages -d dist"
|
318 | }
|
319 | ```
|
320 |
|
321 | And then to publish everything from your `dist` folder to your `gh-pages` branch, you'd run this:
|
322 |
|
323 | ```shell
|
324 | npm run deploy
|
325 | ```
|
326 |
|
327 | ## Debugging
|
328 |
|
329 | To get additional output from the `gh-pages` script, set `NODE_DEBUG=gh-pages`. For example:
|
330 |
|
331 | ```shell
|
332 | NODE_DEBUG=gh-pages npm run deploy
|
333 | ```
|
334 |
|
335 | ## Dependencies
|
336 |
|
337 | 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](https://github.com/tschaub/gh-pages/issues).
|
338 |
|
339 | [![Current Status](https://secure.travis-ci.org/tschaub/gh-pages.svg?branch=master)](https://travis-ci.org/tschaub/gh-pages)
|
340 |
|
341 | ## Tips
|
342 |
|
343 | ### when get error `branch already exists`
|
344 | ```
|
345 | { ProcessError: fatal: A branch named 'gh-pages' already exists.
|
346 |
|
347 | at ChildProcess.<anonymous> (~/node_modules/gh-pages/lib/git.js:42:16)
|
348 | at ChildProcess.emit (events.js:180:13)
|
349 | at maybeClose (internal/child_process.js:936:16)
|
350 | at Process.ChildProcess._handle.onexit (internal/child_process.js:220:5)
|
351 | code: 128,
|
352 | message: 'fatal: A branch named \'gh-pages\' already exists.\n',
|
353 | name: 'ProcessError' }
|
354 | ```
|
355 |
|
356 | When processing `gh-pages` module generate file in`.cache/` and if stuck some reason like wrong password
|
357 | it will not automatically cleanup
|
358 |
|
359 | Run `~node_modules/gh-pages/bin/gh-pages-clean`
|
360 | or remove `~node_modules/gh-pages/.cache`
|
361 |
|
\ | No newline at end of file |