Skip to content

Commit

Permalink
docs: improve README
Browse files Browse the repository at this point in the history
  • Loading branch information
EndBug committed Jan 20, 2022
1 parent 0e1feea commit 03fca92
Showing 1 changed file with 33 additions and 16 deletions.
49 changes: 33 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,15 @@
[![Public workflows that use this action.](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi-endbug.vercel.app%2Fapi%2Fgithub-actions%2Fused-by%3Faction%3DEndBug%2Fadd-and-commit%26badge%3Dtrue)](https://github.com/search?o=desc&q=EndBug+add-and-commit+path%3A.github%2Fworkflows+language%3AYAML&s=&type=Code)
[![All Contributors](https://img.shields.io/github/all-contributors/EndBug/add-and-commit)](#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....
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.
## Table of contents

- [Inputs](#inputs)
- [Outputs](#outputs)
- [FAQs](#faqs)
- [Examples](#examples)
- [Contributors](#contributors)

## Inputs

Expand Down Expand Up @@ -124,7 +129,21 @@ If you want to commit files "across different branches", here are two ways to do

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

### Tokens
## Outputs

The action provides these outputs:

- `committed`: whether the action has created a commit (`'true'` or `'false'`)
- `commit_long_sha`: the full SHA of the commit that has just been created
- `commit_sha`: the short 7-character SHA of the commit that has just been created
- `pushed`: whether the action has pushed to the remote (`'true'` or `'false'`)
- `tagged`: whether the action has created a tag (`'true'` or `'false'`)

For more info on how to use outputs, see ["Context and expression syntax"](https://docs.github.com/en/free-pro-team@latest/actions/reference/context-and-expression-syntax-for-github-actions).

## FAQs

### About tokens

When pushing, the action uses the token that the local git repository has been configured with: that means that if you want to change it you'll need to do it in the steps that run before this action. For example: if you set up your repo with [`actions/checkout`](https://github.com/actions/checkout/) then you have to add the token there.
Changing the token with which the repo is configured can be useful if you want to run CI checks on the commit pushed by this action; anyway, it has to be set up outside of this action.
Expand All @@ -149,20 +168,10 @@ Some users reported that they were getting an error:

If you're getting this error and you're using `actions/checkout@v1`, try upgrading to `actions/checkout@v2`. If you're still having problems after upgrading, feel free to open an issue. Issue ref: [#146](https://github.com/EndBug/add-and-commit/issues/146)

## Outputs

The action provides these outputs:

- `committed`: whether the action has created a commit (`'true'` or `'false'`)
- `commit_long_sha`: the full SHA of the commit that has just been created
- `commit_sha`: the short 7-character SHA of the commit that has just been created
- `pushed`: whether the action has pushed to the remote (`'true'` or `'false'`)
- `tagged`: whether the action has created a tag (`'true'` or `'false'`)

For more info on how to use outputs, see ["Context and expression syntax"](https://docs.github.com/en/free-pro-team@latest/actions/reference/context-and-expression-syntax-for-github-actions).

## Examples

### Different author/committer configurations

If you don't want to use your GitHub username for the CI commits, you can use the `default_author` option to make it appear as if it was made by "github-actions"

<img src="https://user-images.githubusercontent.com/26386270/115738624-80b51780-a38d-11eb-9bbe-77461654274c.png" height=40/>
Expand Down Expand Up @@ -200,6 +209,8 @@ You can also use the `committer_name` and `committer_email` inputs to make it ap
committer_email: 41898282+github-actions[bot]@users.noreply.github.com
```

### Automated linting

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
Expand Down Expand Up @@ -234,6 +245,8 @@ jobs:
add: '*.js'
```

### Running the action in a different directory

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
Expand Down Expand Up @@ -322,6 +335,10 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d

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

### Additional credits

This action is inspired by [`git-auto-commit-action`](https://github.com/stefanzweifel/git-auto-commit-action) by [Stefan Zweifel](https://github.com/stefanzweifel).

## License

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

0 comments on commit 03fca92

Please sign in to comment.