add-and-commit/README.md

# Add & Commit
<a href="https://github.com/search?o=desc&q=EndBug%2Fadd-and-commit+path%3A.github%2Fworkflows+language%3AYAML&s=&type=Code" target="_blank" title="Public workflows that use this action."><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi-git-master.endbug.vercel.app%2Fapi%2Fgithub-actions%2Fused-by%3Faction%3DEndBug%2Fadd-and-commit%26badge%3Dtrue" alt="Public workflows that use this action."></a>
[![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat)](#contributors-)

You can use this GitHub Action to commit changes made in your workflow run directly to your repo: for example, you use it to lint your code, update documentation, commit updated builds, etc....

This is **heavily** inspired by [git-auto-commit-action](https://github.com/stefanzweifel/git-auto-commit-action) (by [Stefan Zweifel](https://github.com/stefanzweifel)): that action automatically detects changed files and commits them. While this is useful for most situations, this doesn't commit untracked files and can sometimes commit unintended changes (such as `package-lock.json` or similar, that may have happened during previous steps).  
This action lets you choose the path that you want to use when adding & committing changes so that it works as you would normally do using `git` on your machine.

## Usage

Add a step like this to your workflow:

```yaml
- uses: EndBug/add-and-commit@v5 # You can change this to use a specific version
  with:
    # The arguments for the `git add` command (see the paragraph below for more info)
    # Default: '.'
    add: 'src'

    # The name of the user that will be displayed as the author of the commit
    # Default: author of the commit that triggered the run
    author_name: Your Name

    # The email of the user that will be displayed as the author of the commit
    # Default: author of the commit that triggered the run
    author_email: mail@example.com

    # Name of the branch to use, if different from the one that triggered the workflow
    # Default: the branch that triggered the run
    branch: some-branch

    # The local path to the directory where your repository is located. You should use actions/checkout first to set it up
    # Default: '.'
    cwd: './path/to/the/repo'

    # The message for the commit
    # Default: 'Commit from GitHub Actions (name of the workflow)'
    message: 'Your commit message'

    # The arguments for the `git rm` command (see the paragraph below for more info)
    # Default: ''
    remove: "./dir/old_file.js"

    # Whether to use the --signoff option on `git commit` (only `true` and `false` are accepted)
    # Default: false
    signoff: true

    # Arguments for the git tag command (the tag name always needs to be the first word not preceded by an hyphen)
    # Default: ''
    tag: "v1.0.0 --force"

  env:
    # This is necessary in order to push a commit to the repo
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged
```

### Environment variables:

The only `env` variable required is the token for the action to run: GitHub generates one automatically, but you need to pass it through `env` to make it available to actions. You can find more about `GITHUB_TOKEN` [here](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret).  
That said, you can just copy the example line and not worry about it. If you do want to use a different token you can pass that in, but I wouldn't see any possible advantage in doing so.

### Adding files:

The action adds files using a regular `git add` command, so you can put every kind of argument in the `add` option. For example, if you want to force-add a file: `./path/to/file.txt --force`.  
The script will not stop if one of the git commands fails. E.g.: if your command shows a "fatal: pathspec 'yourFile' did not match any files" error the action will go on.

### Deleting files:

You can delete files with the `remove` option: that runs a `git rm` command that will stage the files in the given path for removal. As with the `add` argument, you can use every option `git rm` allows (e.g. add `--force` to ignore `.gitignore` rules).  
The script will not stop if one of the git commands fails. E.g.: if your command shows a "fatal: pathspec 'yourFile' did not match any files" error the action will go on.

### Tagging:

You can use the `tag` option to enter the arguments for a `git add` command. In order for the action to isolate the tag name from the rest of the arguments, it should be the first word not preceded by an hyphen (e.g. `-a tag-name -m "some other stuff"` is ok).

### Examples:

Do you want to lint your JavaScript files, located in the `src` folder, with ESLint, so that fixable changes are done without your intervention? You can use a workflow like this:

```yaml
name: Lint source code
on: push

jobs: 
  run:
    name: Lint with ESLint
    runs-on: ubuntu-latest
    steps: 
    - name: Checkout repo
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v1
      with:
        node-version: 12.x
    
    - name: Install dependencies
      run: npm install

    - name: Update source code
      run: eslint "src/**" --fix

    - name: Commit changes
      uses: EndBug/add-and-commit@v5
      with:
        author_name: Your Name
        author_email: mail@example.com
        message: "Your commit message"
        add: "*.js"
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

If you need to run the action on a repository that is not located in [`$GITHUB_WORKSPACE`](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables#default-environment-variables), you can use the `cwd` option: the action uses a `cd` normal command, so the path should follow bash standards.

```yaml
name: Use a different repository directory
on: push

jobs: 
  run:
    name: Add a text file
    runs-on: ubuntu-latest

    steps:
      # If you need to, you can check out your repo to a different location
      - uses: actions/checkout@v2
        with:
          path: "./pathToRepo/"

      # You can make whatever type of change to the repo...
      - run: echo "123" > ./pathToRepo/file.txt

      # ...and then use the action as you would normally do, but providing the path to the repo
      - uses: EndBug/add-and-commit@v5
        with:
          message: "Add the very useful text file"
          add: "*.txt --force"
          cwd: "./pathToRepo/"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tr>
    <td align="center"><a href="https://github.com/EndBug"><img src="https://avatars1.githubusercontent.com/u/26386270?v=4" width="100px;" alt=""/><br /><sub><b>Federico Grandi</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/commits?author=EndBug" title="Code">💻</a> <a href="https://github.com/EndBug/add-and-commit/commits?author=EndBug" title="Documentation">📖</a></td>
    <td align="center"><a href="https://github.com/jactor-rises"><img src="https://avatars3.githubusercontent.com/u/14565088?v=4" width="100px;" alt=""/><br /><sub><b>Tor Egil Jacobsen</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/commits?author=jactor-rises" title="Code">💻</a></td>
    <td align="center"><a href="https://twitter.com/yelizariev"><img src="https://avatars0.githubusercontent.com/u/186131?v=4" width="100px;" alt=""/><br /><sub><b>Ivan Yelizariev</b></sub></a><br /><a href="#ideas-yelizariev" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://github.com/jhhughes"><img src="https://avatars2.githubusercontent.com/u/13724293?v=4" width="100px;" alt=""/><br /><sub><b>jhhughes</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/issues?q=author%3Ajhhughes" title="Bug reports">🐛</a></td>
    <td align="center"><a href="https://sunengine.site"><img src="https://avatars3.githubusercontent.com/u/10674646?v=4" width="100px;" alt=""/><br /><sub><b>Дмитрий Океаний</b></sub></a><br /><a href="#ideas-DmitrijOkeanij" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://github.com/brahma-dev"><img src="https://avatars3.githubusercontent.com/u/1793295?v=4" width="100px;" alt=""/><br /><sub><b>Brahma Dev</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/issues?q=author%3Abrahma-dev" title="Bug reports">🐛</a></td>
    <td align="center"><a href="https://github.com/felixlapalma"><img src="https://avatars2.githubusercontent.com/u/38389683?v=4" width="100px;" alt=""/><br /><sub><b>Felix Rojo Lapalma</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/issues?q=author%3Afelixlapalma" title="Bug reports">🐛</a></td>
  </tr>
  <tr>
    <td align="center"><a href="http://robinwijnant.me"><img src="https://avatars3.githubusercontent.com/u/33033209?v=4" width="100px;" alt=""/><br /><sub><b>Robin Wijnant</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/issues?q=author%3ARobinWijnant" title="Bug reports">🐛</a> <a href="https://github.com/EndBug/add-and-commit/commits?author=RobinWijnant" title="Code">💻</a></td>
    <td align="center"><a href="https://github.com/onilton"><img src="https://avatars2.githubusercontent.com/u/725676?v=4" width="100px;" alt=""/><br /><sub><b>Onilton Maciel</b></sub></a><br /><a href="#ideas-onilton" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://github.com/jsoref"><img src="https://avatars0.githubusercontent.com/u/2119212?v=4" width="100px;" alt=""/><br /><sub><b>Josh Soref</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/commits?author=jsoref" title="Documentation">📖</a></td>
    <td align="center"><a href="https://github.com/ToMe25"><img src="https://avatars1.githubusercontent.com/u/38815969?v=4" width="100px;" alt=""/><br /><sub><b>ToMe25</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/commits?author=ToMe25" title="Code">💻</a> <a href="#ideas-ToMe25" title="Ideas, Planning, & Feedback">🤔</a></td>
    <td align="center"><a href="https://github.com/JonasJacobsUserspace"><img src="https://avatars0.githubusercontent.com/u/59708720?v=4" width="100px;" alt=""/><br /><sub><b>JonasJacobsUserspace</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/issues?q=author%3AJonasJacobsUserspace" title="Bug reports">🐛</a></td>
    <td align="center"><a href="https://github.com/pvogt09"><img src="https://avatars3.githubusercontent.com/u/50047961?v=4" width="100px;" alt=""/><br /><sub><b>pvogt09</b></sub></a><br /><a href="https://github.com/EndBug/add-and-commit/commits?author=pvogt09" title="Code">💻</a></td>
    <td align="center"><a href="http://hoten.cc"><img src="https://avatars1.githubusercontent.com/u/4071474?v=4" width="100px;" alt=""/><br /><sub><b>Connor Clark</b></sub></a><br /><a href="#ideas-connorjclark" title="Ideas, Planning, & Feedback">🤔</a></td>
  </tr>
</table>

<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## License

This action is distributed under the MIT license, check the [license](LICENSE) for more info.