From 4f09181ebc2679b79ed15f6862d85867031b8fb6 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 14:56:27 -0800 Subject: [PATCH 01/14] Reorder readme sections for a different narrative. It follows this rough outline: 1. Basic "what is this?" info. 2. Install the script. 3. Set up your project for the script. 4. Run the script. - Options manual. 5. Configuration. --- readme.md | 47 +++++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/readme.md b/readme.md index 8a5f013..8e55330 100644 --- a/readme.md +++ b/readme.md @@ -4,28 +4,13 @@ This is a script for deploying generated files to a git branch, such as when bui For an example of use, see [X1011/verge-mobile-bingo](https://github.com/X1011/verge-mobile-bingo). For development info, see [contributing.md](contributing.md). -## configuration -Download the script (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`) and edit these variables within it as needed to fit your project: +## installation -- **deploy_directory**: root of the tree of files to deploy -- **deploy_branch**: branch to commit files to and push to origin -- **default_username**, **default_email**: identity to use for git commits if none is set already. Useful for CI servers. -- **repo**: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** +Download the script and make sure it is executable: (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`). That's it! -You can also define any of variables using environment variables and configuration files: +## repository setup -- `GIT_DEPLOY_DIR` -- `GIT_DEPLOY_BRANCH` -- `GIT_DEPLOY_REPO` - -The script will set these variables in this order of preference: - -1. Defaults set in the script itself. -2. Environment variables. -3. `.env` file in the path where you're running the script. -4. File specified on the command-line (see the `-c` option below). - -Whatever values set later in this list will override those set earlier. +TBD ## run Do this every time you want to deploy, or have your CI server do it. @@ -47,4 +32,26 @@ Do this every time you want to deploy, or have your CI server do it. `-v`, `--verbose`: echo expanded commands as they are executed, using the xtrace option. This can be useful for debugging, as the output will include the values of variables that are being used, such as $commit_title and $deploy_directory. However, the script makes special effort to not output the value of $repo, as it may contain a secret authentication token. -`-e`, `--allow-empty`: allow deployment of an empty directory. By default, the script will abort if `deploy_directory` is empty. \ No newline at end of file +`-e`, `--allow-empty`: allow deployment of an empty directory. By default, the script will abort if `deploy_directory` is empty. + +## configuration + +- **deploy_directory**: root of the tree of files to deploy +- **deploy_branch**: branch to commit files to and push to origin +- **default_username**, **default_email**: identity to use for git commits if none is set already. Useful for CI servers. +- **repo**: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** + +You can also define any of variables using environment variables and configuration files: + +- `GIT_DEPLOY_DIR` +- `GIT_DEPLOY_BRANCH` +- `GIT_DEPLOY_REPO` + +The script will set these variables in this order of preference: + +1. Defaults set in the script itself. +2. Environment variables. +3. `.env` file in the path where you're running the script. +4. File specified on the command-line (see the `-c` option below). + +Whatever values set later in this list will override those set earlier. \ No newline at end of file From 436c8d45927a96495cb8f0896a433a7be3e4fcd7 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:16:13 -0800 Subject: [PATCH 02/14] Remove 'repository setup' section of readme. --- readme.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/readme.md b/readme.md index 8e55330..a7afba1 100644 --- a/readme.md +++ b/readme.md @@ -8,10 +8,6 @@ For an example of use, see [X1011/verge-mobile-bingo](https://github.com/X1011/v Download the script and make sure it is executable: (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`). That's it! -## repository setup - -TBD - ## run Do this every time you want to deploy, or have your CI server do it. From 4e9bf3dbf584b4feab5ee40a928be6e3ce059bd7 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:20:28 -0800 Subject: [PATCH 03/14] Add a little more info to 'options' in the readme. --- readme.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/readme.md b/readme.md index a7afba1..19e24a7 100644 --- a/readme.md +++ b/readme.md @@ -18,6 +18,13 @@ Do this every time you want to deploy, or have your CI server do it. 5. run `./deploy.sh` ### options + +This is the syntax for setting the script's options on the command-line: + +`deploy.sh [-c ] []` + +Available options: + `-h`, `--help`: show the program's help info. `-c`, `--config-file`: specify a file that overrides the script's default configuration, or those values set in `.env`. The syntax for this file should be normal `var=value` declarations. __This option _must_ come first on the command-line__. From 9d6344fac70c9f3000162c7313d7fe8b26668ec4 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:21:49 -0800 Subject: [PATCH 04/14] Put 'configuration' section before 'run'. --- readme.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/readme.md b/readme.md index 19e24a7..dbd889b 100644 --- a/readme.md +++ b/readme.md @@ -8,6 +8,28 @@ For an example of use, see [X1011/verge-mobile-bingo](https://github.com/X1011/v Download the script and make sure it is executable: (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`). That's it! +## configuration + +- **deploy_directory**: root of the tree of files to deploy +- **deploy_branch**: branch to commit files to and push to origin +- **default_username**, **default_email**: identity to use for git commits if none is set already. Useful for CI servers. +- **repo**: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** + +You can also define any of variables using environment variables and configuration files: + +- `GIT_DEPLOY_DIR` +- `GIT_DEPLOY_BRANCH` +- `GIT_DEPLOY_REPO` + +The script will set these variables in this order of preference: + +1. Defaults set in the script itself. +2. Environment variables. +3. `.env` file in the path where you're running the script. +4. File specified on the command-line (see the `-c` option below). + +Whatever values set later in this list will override those set earlier. + ## run Do this every time you want to deploy, or have your CI server do it. @@ -36,25 +58,3 @@ Available options: `-v`, `--verbose`: echo expanded commands as they are executed, using the xtrace option. This can be useful for debugging, as the output will include the values of variables that are being used, such as $commit_title and $deploy_directory. However, the script makes special effort to not output the value of $repo, as it may contain a secret authentication token. `-e`, `--allow-empty`: allow deployment of an empty directory. By default, the script will abort if `deploy_directory` is empty. - -## configuration - -- **deploy_directory**: root of the tree of files to deploy -- **deploy_branch**: branch to commit files to and push to origin -- **default_username**, **default_email**: identity to use for git commits if none is set already. Useful for CI servers. -- **repo**: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** - -You can also define any of variables using environment variables and configuration files: - -- `GIT_DEPLOY_DIR` -- `GIT_DEPLOY_BRANCH` -- `GIT_DEPLOY_REPO` - -The script will set these variables in this order of preference: - -1. Defaults set in the script itself. -2. Environment variables. -3. `.env` file in the path where you're running the script. -4. File specified on the command-line (see the `-c` option below). - -Whatever values set later in this list will override those set earlier. \ No newline at end of file From eb92c7756e995b03e203f9f0d6d698dc466b4ca1 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:27:11 -0800 Subject: [PATCH 05/14] Replace in-script variable docs with environment variables. --- readme.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/readme.md b/readme.md index dbd889b..7704f90 100644 --- a/readme.md +++ b/readme.md @@ -10,17 +10,13 @@ Download the script and make sure it is executable: (`wget https://github.com/X1 ## configuration -- **deploy_directory**: root of the tree of files to deploy -- **deploy_branch**: branch to commit files to and push to origin -- **default_username**, **default_email**: identity to use for git commits if none is set already. Useful for CI servers. -- **repo**: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** +- `GIT_DEPLOY_DIR`: root of the tree of files to deploy +- `GIT_DEPLOY_BRANCH`: branch to commit files to and push to origin +- `GIT_DEPLOY_USERNAME`, `GIT_DEPLOY_EMAIL`: identity to use for git commits if none is set already. Useful for CI servers. +- `GIT_DEPLOY_REPO`: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** You can also define any of variables using environment variables and configuration files: -- `GIT_DEPLOY_DIR` -- `GIT_DEPLOY_BRANCH` -- `GIT_DEPLOY_REPO` - The script will set these variables in this order of preference: 1. Defaults set in the script itself. From cdfea0432b546ea937e5ab72250ab34712a6174d Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:29:20 -0800 Subject: [PATCH 06/14] Give 'username' and 'email' var docs their own bullet-items. --- readme.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 7704f90..9824ae1 100644 --- a/readme.md +++ b/readme.md @@ -12,7 +12,8 @@ Download the script and make sure it is executable: (`wget https://github.com/X1 - `GIT_DEPLOY_DIR`: root of the tree of files to deploy - `GIT_DEPLOY_BRANCH`: branch to commit files to and push to origin -- `GIT_DEPLOY_USERNAME`, `GIT_DEPLOY_EMAIL`: identity to use for git commits if none is set already. Useful for CI servers. +- `GIT_DEPLOY_USERNAME`: name used for git commits made by the script. Useful for CI servers. +- `GIT_DEPLOY_EMAIL`: email address used for git commits. Useful for CI servers. - `GIT_DEPLOY_REPO`: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** You can also define any of variables using environment variables and configuration files: From 04d33c6b8284a919350094cd2498e59c14ae8a17 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 15:46:53 -0800 Subject: [PATCH 07/14] Semi-rewrite docs for the variables cascade. --- readme.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/readme.md b/readme.md index 9824ae1..16dfa6b 100644 --- a/readme.md +++ b/readme.md @@ -10,22 +10,21 @@ Download the script and make sure it is executable: (`wget https://github.com/X1 ## configuration +These are the variables that the script uses for its settings: + - `GIT_DEPLOY_DIR`: root of the tree of files to deploy - `GIT_DEPLOY_BRANCH`: branch to commit files to and push to origin - `GIT_DEPLOY_USERNAME`: name used for git commits made by the script. Useful for CI servers. - `GIT_DEPLOY_EMAIL`: email address used for git commits. Useful for CI servers. - `GIT_DEPLOY_REPO`: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** -You can also define any of variables using environment variables and configuration files: - -The script will set these variables in this order of preference: - -1. Defaults set in the script itself. -2. Environment variables. -3. `.env` file in the path where you're running the script. -4. File specified on the command-line (see the `-c` option below). +These variables can be set in a number of different places, and will be set or overridden like this: -Whatever values set later in this list will override those set earlier. +1. If nothing is specified the script uses its internal defaults. +2. An environment variable overrides the script's defaults. +3. A variable set in an `.env` file where you're running the script overrides an environment variable. +4. A variable set in a file specified on the command-line (see the `-c`/`--config` option) overrides `.env` and the environment. +5. Command-line options override everything. ## run Do this every time you want to deploy, or have your CI server do it. From 8a8a4f6ae39ddf213566f52bbe0750a84756ec86 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 16:03:57 -0800 Subject: [PATCH 08/14] Break out config var definitions into bullets with default values. This tree of unordered-list-items could be further broken up into a table. --- readme.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/readme.md b/readme.md index 16dfa6b..e13caa5 100644 --- a/readme.md +++ b/readme.md @@ -12,11 +12,26 @@ Download the script and make sure it is executable: (`wget https://github.com/X1 These are the variables that the script uses for its settings: -- `GIT_DEPLOY_DIR`: root of the tree of files to deploy -- `GIT_DEPLOY_BRANCH`: branch to commit files to and push to origin -- `GIT_DEPLOY_USERNAME`: name used for git commits made by the script. Useful for CI servers. -- `GIT_DEPLOY_EMAIL`: email address used for git commits. Useful for CI servers. -- `GIT_DEPLOY_REPO`: repository to deploy to. Must be readable and writable. The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** +- `GIT_DEPLOY_DIR` + - Folder containing the files to deploy + - Default: `./dist` +- `GIT_DEPLOY_BRANCH` + - Dranch to which the deployed files are committed + - Default: `gh-pages` +- `GIT_DEPLOY_USERNAME` + - Name used for git commits made by the script + - Default: `deploy.sh` + - Useful for running on a CI server. +- `GIT_DEPLOY_EMAIL` + - Email address used for git commits. + - Default: `` + - Useful for running on a CI server. +- `GIT_DEPLOY_REPO` + - Remote repository to deploy to. + - Default: `origin` + - This remote _must_ be readable and writable. + - _Note_ - The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git + - **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** These variables can be set in a number of different places, and will be set or overridden like this: From fd1fc6dd1578841013b5daffb3b4ae0debba0bd8 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 20 Dec 2015 16:14:19 -0800 Subject: [PATCH 09/14] Expand the definition of GIT_DEPLOY_REPO a little. --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index e13caa5..89b0cdf 100644 --- a/readme.md +++ b/readme.md @@ -27,7 +27,7 @@ These are the variables that the script uses for its settings: - Default: `` - Useful for running on a CI server. - `GIT_DEPLOY_REPO` - - Remote repository to deploy to. + - Remote repository to deploy to. It can be either a named remote, or a URL. - Default: `origin` - This remote _must_ be readable and writable. - _Note_ - The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git From ea740124b4366a8afd16b5651e3845bd9a36bd1d Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Mon, 21 Dec 2015 10:56:37 -0800 Subject: [PATCH 10/14] Combine "configure" and "options" sections. --- readme.md | 101 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 52 insertions(+), 49 deletions(-) diff --git a/readme.md b/readme.md index 89b0cdf..2674da3 100644 --- a/readme.md +++ b/readme.md @@ -8,64 +8,67 @@ For an example of use, see [X1011/verge-mobile-bingo](https://github.com/X1011/v Download the script and make sure it is executable: (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`). That's it! -## configuration - -These are the variables that the script uses for its settings: - -- `GIT_DEPLOY_DIR` - - Folder containing the files to deploy - - Default: `./dist` -- `GIT_DEPLOY_BRANCH` - - Dranch to which the deployed files are committed - - Default: `gh-pages` -- `GIT_DEPLOY_USERNAME` - - Name used for git commits made by the script - - Default: `deploy.sh` - - Useful for running on a CI server. -- `GIT_DEPLOY_EMAIL` - - Email address used for git commits. - - Default: `` - - Useful for running on a CI server. -- `GIT_DEPLOY_REPO` - - Remote repository to deploy to. It can be either a named remote, or a URL. - - Default: `origin` - - This remote _must_ be readable and writable. - - _Note_ - The default of "origin" will not work on Travis CI, since it uses the read-only git protocol. In that case, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: repo=https://$GITHUB_TOKEN@github\.com/user/repo.git - - **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** - -These variables can be set in a number of different places, and will be set or overridden like this: - -1. If nothing is specified the script uses its internal defaults. -2. An environment variable overrides the script's defaults. -3. A variable set in an `.env` file where you're running the script overrides an environment variable. -4. A variable set in a file specified on the command-line (see the `-c`/`--config` option) overrides `.env` and the environment. -5. Command-line options override everything. +## options & settings -## run -Do this every time you want to deploy, or have your CI server do it. +The script looks for settings in a few places, in this order: -1. check out the branch or commit of the source you want to use. The script will use this commit to generate a message when it makes its own commit on the deploy branch. -2. generate the files in `deploy_directory` -3. make sure you have no uncommitted changes in git's index. The script will abort if you do. (It's ok to have uncommitted files in the work tree; the script does not touch the work tree.) -4. if `deploy_directory` is a relative path (the default is), make sure you are in the directory you want to resolve against. (For the default, this means you should be in the project's root.) -5. run `./deploy.sh` + 1. Environment variables. + 2. Your project's "dotenv" file (`.env`), if it exists. + 3. A configuration file specified in the command-line. + 4. Specific values specified on the command-line. + +Settings set in later places will override those set earlier. For anything that doesn't get set in any of these places, the script will fall back on its built-in defaults. + +### commmand-line: + +``` +deploy.sh [-c ] [] [ [ []]] +``` -### options +### list of options -This is the syntax for setting the script's options on the command-line: +- `-h`, `--help`: show the program's help info. -`deploy.sh [-c ] []` +- `-c`, `--config-file`: specify a configuration file. + - This option **_must_ come first** on the command-line. + - Syntax for this file (and `.env`) should be compatible with [other "dotenv" libraries](https://duckduckgo.com/?q=dotenv): + + ``` + # Comment + VAR_1=value + VAR_2="another value" + ``` -Available options: +- `-m`, `--message `: specify message to be used for the commit on `deploy_branch`. By default, the message is the title of the source commit, prepended with 'publish: '. -`-h`, `--help`: show the program's help info. +- `-n`, `--no-hash`: don't append the hash of the source commit to the commit message. + - By default, the hash will be appended in a new paragraph, regardless of whether a message was specified with `-m`. + - Set with `GIT_DEPLOY_APPEND_HASH` (default: `true`). -`-c`, `--config-file`: specify a file that overrides the script's default configuration, or those values set in `.env`. The syntax for this file should be normal `var=value` declarations. __This option _must_ come first on the command-line__. +- `-v`, `--verbose`: echo expanded commands as they are executed, using the xtrace option. + - This can be useful for debugging, as the output will include the values of internal variables, such as `$commit_title` and `$deploy_directory`. However, the script makes special effort to not output the value of `$repo`, as it may contain a secret authentication token. -`-m`, `--message `: specify message to be used for the commit on `deploy_branch`. By default, the message is the title of the source commit, prepended with 'publish: '. +- `-e`, `--allow-empty`: allow deployment of an empty directory. + - By default, the script will abort if the deploy directory is empty. Letting the script complete can be useful for troubleshooting though. -`-n`, `--no-hash`: don't append the hash of the source commit to the commit message on `deploy_branch`. By default, the hash will be appended in a new paragraph, regardless of whether a message was specified with `-m`. +- ` [ []]`: the source and target of the deployment. These can also be set with these variables: + - `GIT_DEPLOY_DIR`: folder containing the files to deploy. If this folder doesn't exist (or is empty), the script will abort. Defaults to `./dist`. + - `GIT_DEPLOY_BRANCH`: branch to which the deployable files are committed. If this branch doesn't exist, the script will automatically create it. Defaults to `gh-pages`. + - `GIT_DEPLOY_REPO`: remote repository to deploy to. It can be either a named remote, or a URL. Defaults to `origin`. + - This remote _must_ be readable and writable, as the script will push the deploy-branch to it, or fail. + - _Note_ - The default of "origin" will not work on Travis CI, or any other utility that uses the read-only git protocol. In these cases, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: GIT_DEPLOY_REPO=https://$GITHUB_TOKEN@github\.com/user/repo.git + - **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** -`-v`, `--verbose`: echo expanded commands as they are executed, using the xtrace option. This can be useful for debugging, as the output will include the values of variables that are being used, such as $commit_title and $deploy_directory. However, the script makes special effort to not output the value of $repo, as it may contain a secret authentication token. +- _Commiter identity_: attribution info used in script's git commits. + - `GIT_DEPLOY_USERNAME`: committer name. Defaults to `deploy.sh`. + - `GIT_DEPLOY_EMAIL`: committer email address. Defaults to ``. + - This is useful for running deployments from a CI server, and otherwise showing who made what deployments from where in the commit log. -`-e`, `--allow-empty`: allow deployment of an empty directory. By default, the script will abort if `deploy_directory` is empty. +## run +Do this every time you want to deploy, or have your CI server do it. + +1. check out the branch or commit of the source you want to use. The script will use this commit to generate a message when it makes its own commit on the deploy branch. +2. generate the files in `deploy_directory` +3. make sure you have no uncommitted changes in git's index. The script will abort if you do. (It's ok to have uncommitted files in the work tree; the script does not touch the work tree.) +4. if `deploy_directory` is a relative path (the default is), make sure you are in the directory you want to resolve against. (For the default, this means you should be in the project's root.) +5. run `./deploy.sh` From b16b511729c86b2815282efe2b55735545e19988 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 10 Jan 2016 15:14:20 -0800 Subject: [PATCH 11/14] Tweaks and reorderings to readme's options and settings section. --- readme.md | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/readme.md b/readme.md index 2674da3..2b34ea2 100644 --- a/readme.md +++ b/readme.md @@ -25,7 +25,7 @@ Settings set in later places will override those set earlier. For anything that deploy.sh [-c ] [] [ [ []]] ``` -### list of options +### options & settings - `-h`, `--help`: show the program's help info. @@ -39,30 +39,40 @@ deploy.sh [-c ] [] [ [ []]] VAR_2="another value" ``` -- `-m`, `--message `: specify message to be used for the commit on `deploy_branch`. By default, the message is the title of the source commit, prepended with 'publish: '. +- `-m`, `--message `: specify message to be used when committing to the deployed branch. + - By default, the message is the title of the source commit, prepended with `publish: `. -- `-n`, `--no-hash`: don't append the hash of the source commit to the commit message. - - By default, the hash will be appended in a new paragraph, regardless of whether a message was specified with `-m`. - - Set with `GIT_DEPLOY_APPEND_HASH` (default: `true`). +- `-n`, `--no-hash`: skip appending the hash of the source commit to the commit message. + - The hash would otherwise be appended as a new paragraph in the commit message, keeping it separate from the text (see `-m`). + - Setting: `GIT_DEPLOY_APPEND_HASH` (default: `true`). -- `-v`, `--verbose`: echo expanded commands as they are executed, using the xtrace option. +- `-v`, `--verbose`: echo expanded commands as they are executed. - This can be useful for debugging, as the output will include the values of internal variables, such as `$commit_title` and `$deploy_directory`. However, the script makes special effort to not output the value of `$repo`, as it may contain a secret authentication token. -- `-e`, `--allow-empty`: allow deployment of an empty directory. - - By default, the script will abort if the deploy directory is empty. Letting the script complete can be useful for troubleshooting though. +- `-e`, `--allow-empty`: allow committing and deployment of an empty directory. + - Without this option, the script will abort if the deploy directory is empty. This is normally a good safety feature, but overriding it can sometimes or useful or necessary. - ` [ []]`: the source and target of the deployment. These can also be set with these variables: - - `GIT_DEPLOY_DIR`: folder containing the files to deploy. If this folder doesn't exist (or is empty), the script will abort. Defaults to `./dist`. - - `GIT_DEPLOY_BRANCH`: branch to which the deployable files are committed. If this branch doesn't exist, the script will automatically create it. Defaults to `gh-pages`. - - `GIT_DEPLOY_REPO`: remote repository to deploy to. It can be either a named remote, or a URL. Defaults to `origin`. - - This remote _must_ be readable and writable, as the script will push the deploy-branch to it, or fail. - - _Note_ - The default of "origin" will not work on Travis CI, or any other utility that uses the read-only git protocol. In these cases, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: GIT_DEPLOY_REPO=https://$GITHUB_TOKEN@github\.com/user/repo.git - - **Warning: there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails.** + - `GIT_DEPLOY_DIR`: folder containing the files to deploy. + - If this folder doesn't exist (or is empty, see `-e`), the script will abort. It's up to your project's init/build processes to create and populate this folder. + - Default: `./dist` + - `GIT_DEPLOY_BRANCH`: branch to which the deployable files are committed. + - If this branch doesn't exist, the script will automatically create it. After this branch is committed to, it will also be automatically pushed. + - Default: `gh-pages` + - `GIT_DEPLOY_REPO`: remote repository to deploy to. + - It can be either a named remote, or any URL that Git can push to. + - This remote _must_ be readable and writable, as the script will push the deploy-branch to it. If remote is read-only, the script will fail. + - Default: `origin` + - _Note_ - The default of "origin" will not work on Travis CI, or any other utility that uses the read-only git protocol. In these cases, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: + + GIT_DEPLOY_REPO=https://$GITHUB_TOKEN@github\.com/user/repo.git + + - **Warning** - there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails. - _Commiter identity_: attribution info used in script's git commits. - `GIT_DEPLOY_USERNAME`: committer name. Defaults to `deploy.sh`. - `GIT_DEPLOY_EMAIL`: committer email address. Defaults to ``. - - This is useful for running deployments from a CI server, and otherwise showing who made what deployments from where in the commit log. + - Setting these in your different environments (such as your CI server vs local machine) is useful showing who made what deployments from where in the commit log. ## run Do this every time you want to deploy, or have your CI server do it. From 990824fdd43d0717d3a32164541f46c94e5bbe22 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 10 Jan 2016 16:12:19 -0800 Subject: [PATCH 12/14] Relocate and rewrite 'run' docs. --- readme.md | 47 ++++++++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/readme.md b/readme.md index 2b34ea2..3523ba0 100644 --- a/readme.md +++ b/readme.md @@ -8,23 +8,41 @@ For an example of use, see [X1011/verge-mobile-bingo](https://github.com/X1011/v Download the script and make sure it is executable: (`wget https://github.com/X1011/git-directory-deploy/raw/master/deploy.sh && chmod +x deploy.sh`). That's it! -## options & settings +## usage -The script looks for settings in a few places, in this order: +To use this script in a deployment, follow this basic workflow: - 1. Environment variables. - 2. Your project's "dotenv" file (`.env`), if it exists. - 3. A configuration file specified in the command-line. - 4. Specific values specified on the command-line. - -Settings set in later places will override those set earlier. For anything that doesn't get set in any of these places, the script will fall back on its built-in defaults. +1. `git checkout` the commit (or branch or tag) of your project that you want to deploy. +2. Generate a complete copy of the files you want to deploy in some folder within your project. + - This folder should probably be in your project's `.gitignore`. You don't want to accidentally commit this folder to your main branch hierarchy, after all. That's what this script is for! + - Populating your "deploy folder" is out of this script's scope, and largely depends on the specifics of your project. This is where you'd run something like `make build`, a static site generator, etc. +3. Make sure your working directory is clean. + - If you have uncommitted changes in git's _index_, the script will abort. The script needs a clean index in order to function. + - If you have uncommitted files in the _work tree_, that's okay; the script does not touch the work tree, and checking for this should instead be the responsibility of your project's build process. +4. Run `deploy.sh` from your project's root. + - If your project's needs match the script's defaults then that's it! + - Different projects have different needs, names for the "deploy folder", "deploy branch", and other details. You may even see fit to deploy multiple parts of your project with this script, using vastly different settings. All of this is possible, by using configuration files and command-line options detailed below. + - The key though, is that the script looks for _everything_ at paths relative to where you run it. Make sure you're running the script in the correct folder. -### commmand-line: +Following this workflow by hand can be tedious and error-prone, especially if you're using non-default settings. Rather than just running the script, we definitely recommend using this script in an automated build/deployment routine of some kind. Then, you (or your CI server) can make a deployment in a single step. + +### the commmand-line: ``` -deploy.sh [-c ] [] [ [ []]] +deploy.sh [-c ] [] [ [ []]] ``` +### configuration + +The script looks for settings in a few places, in this order: + + 1. Environment variables. + 2. An `.env` file (if it exists). + 3. A configuration file, if it is specified on the command-line. + 4. Values specified on the command-line. + +Settings set in later places will override those set earlier. For anything that doesn't get set in any of these places, the script will fall back on its built-in defaults. + ### options & settings - `-h`, `--help`: show the program's help info. @@ -73,12 +91,3 @@ deploy.sh [-c ] [] [ [ []]] - `GIT_DEPLOY_USERNAME`: committer name. Defaults to `deploy.sh`. - `GIT_DEPLOY_EMAIL`: committer email address. Defaults to ``. - Setting these in your different environments (such as your CI server vs local machine) is useful showing who made what deployments from where in the commit log. - -## run -Do this every time you want to deploy, or have your CI server do it. - -1. check out the branch or commit of the source you want to use. The script will use this commit to generate a message when it makes its own commit on the deploy branch. -2. generate the files in `deploy_directory` -3. make sure you have no uncommitted changes in git's index. The script will abort if you do. (It's ok to have uncommitted files in the work tree; the script does not touch the work tree.) -4. if `deploy_directory` is a relative path (the default is), make sure you are in the directory you want to resolve against. (For the default, this means you should be in the project's root.) -5. run `./deploy.sh` From ac99cdb5eb6421f125f66c015ee6bc1991d54811 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 10 Jan 2016 16:26:29 -0800 Subject: [PATCH 13/14] Shuffle and slightly expand some options/variables docs. --- readme.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/readme.md b/readme.md index 3523ba0..dcfc688 100644 --- a/readme.md +++ b/readme.md @@ -36,7 +36,7 @@ deploy.sh [-c ] [] [ [ []]] The script looks for settings in a few places, in this order: - 1. Environment variables. + 1. Environment variables. Look for `GIT_DEPLOY_VAR_NAME` 2. An `.env` file (if it exists). 3. A configuration file, if it is specified on the command-line. 4. Values specified on the command-line. @@ -70,16 +70,19 @@ Settings set in later places will override those set earlier. For anything that - `-e`, `--allow-empty`: allow committing and deployment of an empty directory. - Without this option, the script will abort if the deploy directory is empty. This is normally a good safety feature, but overriding it can sometimes or useful or necessary. -- ` [ []]`: the source and target of the deployment. These can also be set with these variables: - - `GIT_DEPLOY_DIR`: folder containing the files to deploy. +- ` [ []]`: the source and target of the deployment. + - ``: folder containing the files to deploy. - If this folder doesn't exist (or is empty, see `-e`), the script will abort. It's up to your project's init/build processes to create and populate this folder. - - Default: `./dist` - - `GIT_DEPLOY_BRANCH`: branch to which the deployable files are committed. + - Variable name: `GIT_DEPLOY_DIR` + - Default value: `./dist` + - ``: the branch to which the deployable files are committed. - If this branch doesn't exist, the script will automatically create it. After this branch is committed to, it will also be automatically pushed. - - Default: `gh-pages` - - `GIT_DEPLOY_REPO`: remote repository to deploy to. + - Variable name: `GIT_DEPLOY_BRANCH` + - Default value: `gh-pages` + - ``: the remote repository to which the deploy branch will be pushed. - It can be either a named remote, or any URL that Git can push to. - - This remote _must_ be readable and writable, as the script will push the deploy-branch to it. If remote is read-only, the script will fail. + - This remote _must_ be readable and writable. If remote is read-only, the script will fail. + - Variable name: `GIT_DEPLOY_REPO` - Default: `origin` - _Note_ - The default of "origin" will not work on Travis CI, or any other utility that uses the read-only git protocol. In these cases, it is recommended to store a [GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) in a [secure environment variable](http://docs.travis-ci.com/user/environment-variables/#Secure-Variables) and use it in an HTTPS URL like this: @@ -87,7 +90,7 @@ Settings set in later places will override those set earlier. For anything that - **Warning** - there is currently [an issue](https://github.com/X1011/git-directory-deploy/issues/7) where the repo URL may be output if an operation fails. -- _Commiter identity_: attribution info used in script's git commits. +- _Commiter identity_: attribution info used when the script makes git commits. These settings are not exposed as command-line options, only variables. - `GIT_DEPLOY_USERNAME`: committer name. Defaults to `deploy.sh`. - `GIT_DEPLOY_EMAIL`: committer email address. Defaults to ``. - Setting these in your different environments (such as your CI server vs local machine) is useful showing who made what deployments from where in the commit log. From 07eaa6a614db19e4655f46d66e7841cb21e833e6 Mon Sep 17 00:00:00 2001 From: Matt Pearson Date: Sun, 10 Jan 2016 16:33:29 -0800 Subject: [PATCH 14/14] Move config file syntax explanation into config section. --- readme.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/readme.md b/readme.md index dcfc688..7baa908 100644 --- a/readme.md +++ b/readme.md @@ -36,26 +36,27 @@ deploy.sh [-c ] [] [ [ []]] The script looks for settings in a few places, in this order: - 1. Environment variables. Look for `GIT_DEPLOY_VAR_NAME` + 1. Environment variables. 2. An `.env` file (if it exists). 3. A configuration file, if it is specified on the command-line. 4. Values specified on the command-line. Settings set in later places will override those set earlier. For anything that doesn't get set in any of these places, the script will fall back on its built-in defaults. +For for settings exposed as variables, look for `GIT_DEPLOY_VAR` variable names in the options and settings below. The syntax for `.env` and other configuration files should be compatible with [other "dotenv" libraries](https://duckduckgo.com/?q=dotenv): + +``` +# A Comment +VAR_1=value +VAR_2="another value" +``` + ### options & settings - `-h`, `--help`: show the program's help info. - `-c`, `--config-file`: specify a configuration file. - This option **_must_ come first** on the command-line. - - Syntax for this file (and `.env`) should be compatible with [other "dotenv" libraries](https://duckduckgo.com/?q=dotenv): - - ``` - # Comment - VAR_1=value - VAR_2="another value" - ``` - `-m`, `--message `: specify message to be used when committing to the deployed branch. - By default, the message is the title of the source commit, prepended with `publish: `.