deploy-to-git/README.md

Automatically deploy build artifacts to a Git repository

# deploy-to-git [![npm version](https://badge.fury.io/js/deploy-to-git.svg)](https://badge.fury.io/js/deploy-to-git) [![Build Status](https://travis-ci.org/finom/deploy-to-git.svg?branch=master)](https://travis-ci.org/finom/deploy-to-git)

Automatically or manually deploy build artifacts to a Git repository. The tool works awesome with [semantic-release](https://github.com/semantic-release/semantic-release) and any CI service.

```
npm install --save-dev deploy-to-git
```

## Configuring

Configuration for the tool needs to be placed at ``config.deployToGit`` object inside  ``package.json``.

- ``repository`` - a repository
- ``branch`` - a branch of the repository where you want to push the artifacts
- ``folder`` - a folder where artifacts are generated by the build and where the repository is cloned
- ``script`` - a script which runs the build
- ``commit`` - commit text
- ``user`` - commitee information for Git - an object with keys ``name`` and ``email``
- ``beforePushScript`` (optional) - a command that should be run after a commit (e. g. add needed git tags).

Substrings started with ``$`` are replaced by corresponding environment variables.

## Getting started

Let's say you want to deploy artifacts to branch called ``artifacts``. Let's say used build tool compiles the artifacts to ``build`` folder via NPM script called ``build-my-app``. You'll need:

1. Create ``artifacts`` branch manually and remove all files from it (because you probably create the branch copying main branch contents). Push it to remote repository.
2. Add README or whatever you want to have at this branch.
3. Add ``build`` folder to ``.gitignore`` of your main branch.
4. Configure ``deploy-to-git``

```js
"scripts": {
  "deploy": "deploy-to-git",
  "build-my-app": "a-build-script"
}
"config": {
  "deployToGit": {
      "repository": "git@github.com:owner/your-repo.git",
      "branch": "artifacts",
      "folder": "build",
      "script": "npm run build-my-app",
      "commit": "Automatic commit text",
      "user": {
          "email": "you@example.com",
          "name": "Your name"
      }
  }
}
```

That's it. When you run ``npm run deploy`` the tool does the following:

1. Clone the repository to ``build`` folder.
2. Run script ``npm run build-my-app`` which creates/replaces files at ``build`` folder.
3. Commit and push changes.

Tip: remove ``build`` folder before ``deploy-to-git`` run.

For more info check out [index.js](https://github.com/finom/deploy-to-git/blob/master/index.js).

## Travis CI

To run it on Travis CI use the following format of ``repository`` field: ``https://$GH_TOKEN@github.com/owner/your-repo.git``.  You can generate GH_TOKEN at Github settings and add it to Travis CI manually. For more info just google it ("generate github token", "add environment variable to Travis") :)

It is generated automatically if you use semantic-release-cli.

## semantic-release

Just add ``deploy-to-github`` to ``semantic-release`` script.

```
"deploy": "deploy-to-git",
"semantic-release": "semantic-release pre && npm run deploy && npm publish && semantic-release post",
```

Tip: You can use a release version in a commit message:
```
"commit": "Publising $npm_package_version",
```

## Real example

Real example can be found [there](https://github.com/finom/github-embed). The application is compiled via webpack to ``bundle`` folder and pushed to [gh-pages branch](https://github.com/finom/github-embed/tree/gh-pages).