Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme refactor #25

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
Open

Readme refactor #25

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
4f09181
Reorder readme sections for a different narrative.
Dec 20, 2015
436c8d4
Remove 'repository setup' section of readme.
Dec 20, 2015
4e9bf3d
Add a little more info to 'options' in the readme.
Dec 20, 2015
9d6344f
Put 'configuration' section before 'run'.
Dec 20, 2015
eb92c77
Replace in-script variable docs with environment variables.
Dec 20, 2015
cdfea04
Give 'username' and 'email' var docs their own bullet-items.
Dec 20, 2015
04d33c6
Semi-rewrite docs for the variables cascade.
Dec 20, 2015
8a8a4f6
Break out config var definitions into bullets with default values.
Dec 21, 2015
fd1fc6d
Expand the definition of GIT_DEPLOY_REPO a little.
Dec 21, 2015
ea74012
Combine "configure" and "options" sections.
Dec 21, 2015
b16b511
Tweaks and reorderings to readme's options and settings section.
Jan 10, 2016
990824f
Relocate and rewrite 'run' docs.
Jan 11, 2016
ac99cdb
Shuffle and slightly expand some options/variables docs.
Jan 11, 2016
07eaa6a
Move config file syntax explanation into config section.
Jan 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 91 additions & 44 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,47 +4,94 @@ 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:

- **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: <code>repo=https://$GITHUB_TOKEN@github\.com/<i>user</i>/<i>repo</i>.git</code> **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.

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`

### 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__.

`-m`, `--message <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: '.

`-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`.

`-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.
## installation

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!

## usage

To use this script in a deployment, follow this basic workflow:

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.

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 <CONFIG_FILE>] [<options>] [<directory> [<branch> [<repo>]]]
```

### 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.

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.

- `-m`, `--message <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`: 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.
- 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 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.

- `<directory> [<branch> [<repo>]]`: the source and target of the deployment.
- `<directory>`: 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.
- Variable name: `GIT_DEPLOY_DIR`
- Default value: `./dist`
- `<branch>`: 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.
- Variable name: `GIT_DEPLOY_BRANCH`
- Default value: `gh-pages`
- `<repo>`: 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. 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:
<code>
GIT_DEPLOY_REPO=https://<strong>$GITHUB_TOKEN</strong>@github\.com/<em>user</em>/<em>repo</em>.git
</code>
- **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 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 `<empty>`.
- 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.