diff --git a/.gitignore b/.gitignore index a4d70b0..8bfdd75 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ node_modules *.swp *.swo *.d.ts +.idea *.classpath *.project diff --git a/README.md b/README.md index d536e0c..a98a1a2 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ - [--no-notfound](#no-notfound) - [--no-nojekyll](#no-nojekyll) - [--cname](#cname) + - [--add](#add) - [--dry-run](#dry-run) 7. [📁 Configuration File](#configuration-file) 8. [🌍 Environments](#environments) @@ -77,9 +78,9 @@ You can also and modify your `angular.json` to archive the same: ``` For your convenience, you can also use `prerenderTarget` (which adds the suffix `:prerender:production`). -There is no support for `universalBuildTarget` or `serverTarget` because Github Pages only supports static assets and no Server-Side Rendering! +There is no support for `universalBuildTarget` or `serverTarget` because GitHub Pages only supports static assets and no Server-Side Rendering! -We will then try to deploy the `dist/test/browser` folder to Github Pages. +We will then try to deploy the `dist/test/browser` folder to GitHub Pages. If this is not the folder that you want to serve, you should explicitly specify the directory with the `--dir` option: ```bash @@ -111,7 +112,7 @@ If you already have an existing Angular project on GitHub, skip step 1 and 2. cd your-angular-project ``` -2. By default the Angular CLI initializes a Git repository for you. +2. By default, the Angular CLI initializes a Git repository for you. To add a new remote for GitHub, use the `git remote add` command: ```sh @@ -167,8 +168,8 @@ ng add angular-cli-ghpages --project MYPROJECTNAME ## 🚀 Continuous Delivery If you run this command from a CI/CD environment, the deployment will most likely not work out of the box. -For security reasons, those environments usually have read-only privileges or you haven't set up Git correctly. -Therefore you should take a look at ["personal access tokens" `GH_TOKEN`](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) (which works everywhere) and the ["installation access token" `GITHUB_TOKEN`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token) (which is exclusively provided by GitHub actions). +For security reasons, those environments usually have read-only privileges, or you haven't set up Git correctly. +Therefore, you should take a look at ["personal access tokens" `GH_TOKEN`](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) (which works everywhere) and the ["installation access token" `GITHUB_TOKEN`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token) (which is exclusively provided by GitHub actions). In short: a token replaces username and password and is a safer choice because a token can be revoked at any time. All you need to do is to set an environment variable called `GH_TOKEN` (or `PERSONAL_TOKEN`) in your CI/CD environment. @@ -201,7 +202,7 @@ ng deploy --repo=https://github.com//.git --name="Your - `ng deploy` – The tag `` remains unchanged in your `index.html` - `ng deploy --base-href=/the-repositoryname/` – The tag `` is added to your `index.html` -Specifies the base URL for the application being built. +Specify the base URL for the application being built. Same as `ng build --base-href=/XXX/` **ℹī¸ Please read the next lines carefully, or you will get 404 errors in case of a wrong configuration!** @@ -266,7 +267,7 @@ ng deploy --build-target=test - `ng deploy` – Angular project is build in production mode before the deployment - `ng deploy --no-build` – Angular project is NOT build -Skip build process during deployment. +Skip the build process during deployment. This can be used when you are sure that you haven't changed anything and want to deploy with the latest artifact. This command causes the `--build-target` setting to have no effect. @@ -280,7 +281,7 @@ This specifies the target repository. If none is given as an option, the reposit By default, this command 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, +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. > **ℹī¸ Hint** @@ -340,8 +341,9 @@ With `--no-dotfiles` files starting with `.` are ignored. - `ng deploy` – A `404.html` file is created by default. - `ng deploy --no-notfound` – No `404.html` file is created. -By default a `404.html` file is created, because this is the only known workaround to avoid 404 error messages on GitHub Pages. -For Cloudflare Pages we highly recommend to disable the `404.html` file by setting this switch to true! see [#178](https://github.com/angular-schule/angular-cli-ghpages/issues/178) +By default, a `404.html` file is created, because this is the only known workaround to avoid 404 error messages on GitHub Pages. +For Cloudflare Pages we highly recommend to disable the `404.html` file by setting this switch to true! +See [#178](https://github.com/angular-schule/angular-cli-ghpages/issues/178) #### --no-nojekyll @@ -351,7 +353,7 @@ For Cloudflare Pages we highly recommend to disable the `404.html` file by setti - `ng deploy` – A `.nojekyll` file is created by default. - `ng deploy --no-nojekyll` – No `.nojekyll` file is created. -By default a `.nojekyll` file is created, because we assume you don't want to compile the build again with Jekyll. +By default, a `.nojekyll` file is created, because we assume you don't want to compile the build again with Jekyll. **Explanation:** By creating such a file in the root of your pages repo, you will bypass the Jekyll static site generator on GitHub Pages. @@ -370,6 +372,17 @@ The same applies to `.txt` files in your assets folder: They will just disappear A CNAME file will be created enabling you to use a custom domain. [More information on GitHub Pages using a custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/). +#### --add + +- **optional** +- Default: `false` (boolean) – The existing files will be removed from the branch you'll be pushing to as expected. +- Example: + - `ng deploy --add=true` + +If is set to `true`, it will only add, and never remove existing files. +By default, existing files in the target branch are removed before adding the ones. +[More information](https://www.npmjs.com/package/gh-pages#optionsadd). + #### --dir - **optional** @@ -439,7 +452,7 @@ Now you can just run `ng deploy` without all the options in the command line! ## 🌍 Environments -We have seen `angular-cli-ghpages` running on various environments, like Travis CI, CircleCi or Github Actions. +We have seen `angular-cli-ghpages` running on various environments, like Travis CI, CircleCi or GitHub Actions. Please share your knowledge by writing an article about how to set up the deployment. 1. [GitHub Actions](https://angular.schule/blog/2020-01-everything-github) diff --git a/docs/README_standalone.md b/docs/README_standalone.md index de9738b..f974948 100644 --- a/docs/README_standalone.md +++ b/docs/README_standalone.md @@ -1,6 +1,6 @@ # angular-cli-ghpages: README for the standalone program -In the past this project was a standalone program. +In the past, this project was a standalone program. This is still possible. ## Installation & Setup @@ -85,7 +85,7 @@ Output the version number. Please provide the version number on any bug report! 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, +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. #### --message @@ -125,7 +125,7 @@ In this case provide both `name` and `email` string values to identify the commi - Default: `dist` Directory for all published sources, relative to the current working directory. -**Starting with Angular CLI 6 the build artifacts will be put in a subfolder under `dist`. +**Starting with Angular CLI 6, the build artifacts will be put in a subfolder under `dist`. Please take a look at the `dist` folder to see whether there is a subfolder with your project's name or not.** This option can be used to deploy completely different folders, @@ -139,7 +139,7 @@ which are not related at all to angular. - `npx angular-cli-ghpages` -- Dotfiles are included by default. - `npx angular-cli-ghpages --no-dotfiles` -- Dotfiles are ignored. -The command includes dotfiles by default (e.g `.htaccess` will be committed) +The command includes dotfiles by default (e.g. `.htaccess` will be committed) With `--no-dotfiles` files starting with `.` are ignored. #### --dry-run @@ -161,6 +161,17 @@ Run through without making any changes. This can be very usefull, because it out A CNAME file will be created enabling you to use a custom domain. [More information on Github Pages using a custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/). +#### --add + +- **optional** +- Default: `false` (boolean) – The existing files will be removed from the branch you'll be pushing to as expected. +- Example: + - `npx angular-cli-ghpages --add=true` + +If is set to `true`, it will only add, and never remove existing files. +By default, existing files in the target branch are removed before adding the ones. +[More information](https://www.npmjs.com/package/gh-pages#optionsadd). + ## FAQ Before posting any issue, [please read the FAQ first](https://github.com/angular-schule/angular-cli-ghpages/wiki/FAQ). diff --git a/src/angular-cli-ghpages b/src/angular-cli-ghpages index 6835134..3e7f19e 100755 --- a/src/angular-cli-ghpages +++ b/src/angular-cli-ghpages @@ -65,6 +65,11 @@ commander 'Generate a CNAME file for the specified domain.', defaults.cname ) + .option( + '-a, --add', + 'Only add, and never remove existing files from the GitHub pages branch.', + defaults.add + ) .option( '--dry-run', 'For testing: Run through without making any changes.', diff --git a/src/deploy/schema.json b/src/deploy/schema.json index b4735fa..3729fd7 100644 --- a/src/deploy/schema.json +++ b/src/deploy/schema.json @@ -71,6 +71,11 @@ "description": "Generate a CNAME file for the specified domain.", "default": "" }, + "add": { + "type": "boolean", + "description": "Only add, and never remove existing files from the GitHub pages branch.", + "default": false + }, "dir": { "type": "string", "description": "Overrides the directory for all published sources, relative to the current working directory.", diff --git a/src/engine/defaults.ts b/src/engine/defaults.ts index 65d4cc9..6075781 100644 --- a/src/engine/defaults.ts +++ b/src/engine/defaults.ts @@ -9,6 +9,7 @@ export const defaults = { notfound: true, nojekyll: true, cname: undefined, + add: false, dryRun: false, remote: 'origin', git: 'git' diff --git a/src/engine/engine.ts b/src/engine/engine.ts index 90af3d5..5f47e19 100644 --- a/src/engine/engine.ts +++ b/src/engine/engine.ts @@ -1,10 +1,10 @@ -import { logging } from '@angular-devkit/core'; +import {logging} from '@angular-devkit/core'; import * as fse from 'fs-extra'; import * as path from 'path'; -import { Schema } from '../deploy/schema'; -import { GHPages } from '../interfaces'; -import { defaults } from './defaults'; +import {Schema} from '../deploy/schema'; +import {GHPages} from '../interfaces'; +import {defaults} from './defaults'; import Git from 'gh-pages/lib/git'; @@ -293,22 +293,23 @@ async function publishViaGhPages( if (options.dryRun) { logger.info( `Dry-run / SKIPPED: publishing folder '${dir}' with the following options: ` + - JSON.stringify( - { - dir, - repo: options.repo || 'current working directory (which must be a git repo in this case) will be used to commit & push', - message: options.message, - branch: options.branch, - name: options.name ? `the name '${options.username} will be used for the commit` : 'local or global git user name will be used for the commit', - email: options.email ? `the email '${options.cname} will be used for the commit` : 'local or global git user email will be used for the commit', - dotfiles: options.dotfiles ? `files starting with dot ('.') will be included` : `files starting with dot ('.') will be ignored`, - notfound: options.notfound ? 'a 404.html file will be created' : 'a 404.html file will NOT be created', - nojekyll: options.nojekyll ? 'a .nojekyll file will be created' : 'a .nojekyll file will NOT be created', - cname: options.cname ? `a CNAME file with the content '${options.cname}' will be created` : 'a CNAME file will NOT be created' - }, - null, - ' ' - ) + JSON.stringify( + { + dir, + repo: options.repo || 'current working directory (which must be a git repo in this case) will be used to commit & push', + message: options.message, + branch: options.branch, + name: options.name ? `the name '${options.username} will be used for the commit` : 'local or global git user name will be used for the commit', + email: options.email ? `the email '${options.cname} will be used for the commit` : 'local or global git user email will be used for the commit', + dotfiles: options.dotfiles ? `files starting with dot ('.') will be included` : `files starting with dot ('.') will be ignored`, + notfound: options.notfound ? 'a 404.html file will be created' : 'a 404.html file will NOT be created', + nojekyll: options.nojekyll ? 'a .nojekyll file will be created' : 'a .nojekyll file will NOT be created', + cname: options.cname ? `a CNAME file with the content '${options.cname}' will be created` : 'a CNAME file will NOT be created', + add: options.add ? 'all files will be added to the branch. Existing files will not be removed' : 'existing files will be removed from the branch before adding the new ones', + }, + null, + ' ' + ) ); return; } diff --git a/src/package-lock.json b/src/package-lock.json index 6b9762e..4983a65 100644 --- a/src/package-lock.json +++ b/src/package-lock.json @@ -1,12 +1,12 @@ { "name": "angular-cli-ghpages", - "version": "2.0.0-beta.1", + "version": "2.0.0-beta.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "angular-cli-ghpages", - "version": "2.0.0-beta.1", + "version": "2.0.0-beta.2", "license": "MIT", "dependencies": { "@angular-devkit/architect": "~0.1700.0",