Publish to any gh-pages branch on GitHub (or any other branch on any other remote).
Made for angular-cli users.
Made with Travis-CI in mind.
Brought to you by the angular-buch.com team!
This command is similar to the old github-pages:deploy
command of @angular/cli which was removed in #4385.
The angular-cli-ghpages command is able to push to any branch on any repository. It's made on top of tschaub/gh-pages.
This script works great on Travis-CI. No git credentials must be set up in before. Specific environment variables of Travis-CI are evaluated, too. You will like it!
This command has the following prerequisites:
- Node.js 4.x
- Git 1.7.6 or higher
- optional: Angular project created via angular-cli
To install the command run the following:
npm i -g angular-cli-ghpages
Execute angular-cli-ghpages
in order to deploy the project with a build from dist
folder.
Note: you have to create the dist
folder in before (e.g. ng build --prod
)
Usage:
ng build --prod --base-href "https://USERNAME.github.io/REPOSITORY/"
angular-cli-ghpages [OPTIONS]
there is also a shorter ngh
command available
ng build --prod --base-href "https://USERNAME.github.io/REPOSITORY/"
ngh [OPTIONS]
If you want to push to gh-pages
on the same repository with your default credentials, then just enter ngh
without any options.
- Example:
ngh --help
Output usage information.
- Example:
ngh --version
Output the version number. Please provide the version number on any bug report!
- optional
- Default: url of the origin remote of the current dir (assumes a git repository)
- Example:
ngh --repo=https://GH_TOKEN@github.com/organisation/your-repo.git
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 files are not in a git repository, or if you want to push to another repository,
you can provide the repository URL in the repo
option.
- optional
- Default:
Auto-generated commit
- Example:
ngh --message="What could possibly go wrong?"
The commit message, must be wrapped in quotes.
Some handy additional text is always added,
if the environment variable process.env.TRAVIS
exists (for Travis CI).
- optional
- Default:
gh-pages
- Example:
ngh --branch=other-branch
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.
- optional
- Default: value of
git config user.name
andgit config user.email
- Example:
ngh --name="Displayed Username" --email=mail@example.org
If you are running the command 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.
In this case provide both name
and email
string values to identify the committer.
- optional
- Default: silent
true
(boolean) - Example:
ngh
-- Logging is in silent mode by default.ngh --no-silent
-- Logging shows extended information.
Logging is in silent mode by default. In silent mode log messages are suppressed and error messages are sanitized.
The --no-silent
option enables extended console logging.
Keep this untouched if the repository URL or other information passed to git commands is sensitive!
WARNING: This option should kept like it is if the repository URL or other information passed to git commands is sensitive and should not be logged (== you have a public build server). By default the silent mode is enabled to avoid sensitive data exposure.
- optional
- Default:
dist
Directory for all published sources, relative to the project-root.
Most probably no change is required here.
This option can be used to deploy completely different folders,
which are not related at all to angular.
- optional
- Default: dotfiles
true
(boolean) - Example:
ngh
-- Dotfiles are included by default.ngh --no-dotfiles
-- Dotfiles are ignored.
The command includes dotfiles by default (e.g .htaccess
will be committed)
With --no-dotfiles
files starting with .
are ignored.
For your convenience, the command will recognize the environment variable GH_TOKEN
and will replace this pattern in the --repo
string. Please do NOT disable the silent mode if you have any credentials in the repository URL! Read more about Github tokens here.
In example, the following command runs on our Travis-CI:
angular-cli-ghpages --repo=https://GH_TOKEN@github.com/organisation/your-repo.git --name="Displayed Username" --email=mail@example.orf
You have to treat the GH_TOKEN as secure as a password!
The old github-pages:deploy
command created a 404.html
file in the dist
folder.
This was required to fully support the router PathLocationStrategy
.
Right now you have to copy index.html
to 404.html
on your own.
Please submit an issue if you really want this feature back.
Example:
ng build
cp dist/index.html dist/404.html
angular-cli-ghpages [OPTIONS]
git clone https://github.com/angular-buch/angular-cli-ghpages.git
cd angular-cli-ghpages
npm link
npm link
is very similar to npm install -g
except that instead of downloading the package
from the NPM repo, the just cloned angular-cli-ghpages/
folder becomes the global package.
Now you can use ngh
via the command line.
Please read the official npm-link documentation
and the npm-link cheatsheet for more information.
Code released under the MIT license.