Update README.md

Fixes #212

CHANGELOG.md

@@ -1,235 +1,276 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.12.0...HEAD)
+## [Unreleased](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.14.0...HEAD)
 
 > TBD
 
+## [v4.14.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.13.1...v4.14.0) - 2022-03-18
+
+## Added
+
+- Add `create_branch` option to force create a new branch (#203) @stefanzweifel
+
+## Fixed
+
+- README.md: Updates hyperlink to GH docs (#200) @funkyfuture
+
+## [v4.13.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.13.0...v4.13.1) - 2022-01-13
+
+## Fixed
+
+- Properly disambiguate between branch or file checkout (#199) @kenodegard
+
+## [v4.13.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.12.0...v4.13.0) - 2022-01-10
+
+## Added
+
+- Add `skip_checkout` option (#197) @cmbuckley
+
+## Changed
+
+- Add note on minimum permissions to the docs (#180) @ericcornelissen
 
 ## [v4.12.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.11.0...v4.12.0) - 2021-09-10
 
 ### Added
-- Add `commit_hash` output [#172](https://github.com/stefanzweifel/git-auto-commit-action/pull/172)
 
+- Add `commit_hash` output [#172](https://github.com/stefanzweifel/git-auto-commit-action/pull/172)
 
 ## [v4.11.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.10.0...v4.11.0) - 2021-05-03
 
 ### Added
-- Add `status_options` and `add_options` option [#156](https://github.com/stefanzweifel/git-auto-commit-action/pull/156)
 
+- Add `status_options` and `add_options` option [#156](https://github.com/stefanzweifel/git-auto-commit-action/pull/156)
 
 ## [v4.10.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.9.2...v4.10.0) - 2021-04-12
 
 ### Added
-- Add `disable_globbing` option [#153](https://github.com/stefanzweifel/git-auto-commit-action/issues/153), [#154](https://github.com/stefanzweifel/git-auto-commit-action/pull/154)
 
+- Add `disable_globbing` option [#153](https://github.com/stefanzweifel/git-auto-commit-action/issues/153), [#154](https://github.com/stefanzweifel/git-auto-commit-action/pull/154)
 
 ## [v4.9.2](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.9.1...v4.9.2) - 2021-03-04
 
 ### Fixes
-- Push created annotated tags to remote by using `--follow-tags` and `--atomic` instead of just `--tags` [#146](https://github.com/stefanzweifel/git-auto-commit-action/pull/146)
 
+- Push created annotated tags to remote by using `--follow-tags` and `--atomic` instead of just `--tags` [#146](https://github.com/stefanzweifel/git-auto-commit-action/pull/146)
 
 ## [v4.9.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.9.0...v4.9.1) - 2021-02-23
 
 ### Changed
-- Revert changes made in v4.9.0. A branch will no longer be automatically generated. [#144](https://github.com/stefanzweifel/git-auto-commit-action/pull/144)
 
+- Revert changes made in v4.9.0. A branch will no longer be automatically generated. [#144](https://github.com/stefanzweifel/git-auto-commit-action/pull/144)
 
 ## [v4.9.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.8.0...v4.9.0) - 2021-02-20
 
 ### Changed
-- Automatically create branch if a branch with the given name does not exist [#140](https://github.com/stefanzweifel/git-auto-commit-action/pull/140)
 
+- Automatically create branch if a branch with the given name does not exist [#140](https://github.com/stefanzweifel/git-auto-commit-action/pull/140)
 
 ## [v4.8.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.7.2...v4.8.0) - 2020-12-15
 
 ### Added
+
 - Add `skip_fetch` option to skip the execution of `git-fetch` [#131](https://github.com/stefanzweifel/git-auto-commit-action/pull/131)
 
 ### Changed
-- Update `git fetch` to only fetch the latest commit from remote [#131](https://github.com/stefanzweifel/git-auto-commit-action/pull/131)
 
+- Update `git fetch` to only fetch the latest commit from remote [#131](https://github.com/stefanzweifel/git-auto-commit-action/pull/131)
 
 ## [v4.7.2](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.7.1...v4.7.2) - 2020-10-24
 
 This release basically reverts the Action to the state of `v4.6.0`.
 
 ### Changed
-- Revert change to fix git-checkout with special characters in branch names [#122](https://github.com/stefanzweifel/git-auto-commit-action/pull/122)
 
+- Revert change to fix git-checkout with special characters in branch names [#122](https://github.com/stefanzweifel/git-auto-commit-action/pull/122)
 
 ## [v4.7.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.7.0...v4.7.1) - 2020-10-22
 
 ### Removed
-- Remove `checkout_options` as it broke everything [#120](https://github.com/stefanzweifel/git-auto-commit-action/pull/120/)
 
+- Remove `checkout_options` as it broke everything [#120](https://github.com/stefanzweifel/git-auto-commit-action/pull/120/)
 
 ## [v4.7.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.6.0...v4.7.0) - 2020-10-21
 
 ### Added
-- Add `checkout_options` [#115](https://github.com/stefanzweifel/git-auto-commit-action/pull/115)
 
+- Add `checkout_options` [#115](https://github.com/stefanzweifel/git-auto-commit-action/pull/115)
 
 ## [v4.6.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.5.1...v4.6.0) - 2020-10-11
 
 ### Changed
+
 - Make "commit_message" optional and set default commit message to "Apply automatic changes" [#103](https://github.com/stefanzweifel/git-auto-commit-action/issues/103), [#110](https://github.com/stefanzweifel/git-auto-commit-action/pull/110)
 
 ### Fixes
-- Better support for branch names with special characters in them [#108](https://github.com/stefanzweifel/git-auto-commit-action/pull/108)
 
+- Better support for branch names with special characters in them [#108](https://github.com/stefanzweifel/git-auto-commit-action/pull/108)
 
 ## [v4.5.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.5.0...v4.5.1) - 2020-09-11
 
 ### Removed
+
 - Remove orphan branch feature added in #95 which broke stuff [#98](https://github.com/stefanzweifel/git-auto-commit-action/pull/98)
 
 ## [v4.5.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.4.1...v4.5.0) - 2020-09-10
 
 ### Added
+
 - Create orphan branch if branch name does not exist [#95](https://github.com/stefanzweifel/git-auto-commit-action/pull/95)
 
 ## [v4.4.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.4.0...v4.4.1) - 2020-08-16
 
 ### Changed
-- Include given `file_pattern` in git dirty check [#91](https://github.com/stefanzweifel/git-auto-commit-action/pull/91)
 
+- Include given `file_pattern` in git dirty check [#91](https://github.com/stefanzweifel/git-auto-commit-action/pull/91)
 
 ## [v4.4.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.3.0...v4.4.0) - 2020-06-26
 
 ### Added
-- Add option to skipt the dirty check and always try to create and push a commit [#82](https://github.com/stefanzweifel/git-auto-commit-action/issues/82), [#84](https://github.com/stefanzweifel/git-auto-commit-action/pull/84)
 
+- Add option to skipt the dirty check and always try to create and push a commit [#82](https://github.com/stefanzweifel/git-auto-commit-action/issues/82), [#84](https://github.com/stefanzweifel/git-auto-commit-action/pull/84)
 
 ## [v4.3.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.2.0...v4.3.0) - 2020-05-16
 
 Note: Since v4.3.0 we provide major version tags. You can now use `stefanzweifel/git-auto-commit-action@v4` to always use the latest release of a major version. See [#77](https://github.com/stefanzweifel/git-auto-commit-action/issues/77) for details.
 
 ### Added
-- Add new `push_options`-input. This feature makes it easier for you to force-push commits to a repository. [#78](https://github.com/stefanzweifel/git-auto-commit-action/pull/78), [#72](https://github.com/stefanzweifel/git-auto-commit-action/issues/72)
 
+- Add new `push_options`-input. This feature makes it easier for you to force-push commits to a repository. [#78](https://github.com/stefanzweifel/git-auto-commit-action/pull/78), [#72](https://github.com/stefanzweifel/git-auto-commit-action/issues/72)
 
 ## [v4.2.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.6...v4.2.0) - 2020-05-10
 
 ### Changed
-- Use `${{ github.head_ref }}` as default branch value. Therefore, the branch name when listening for `pull_request`-events is optional. [#75](https://github.com/stefanzweifel/git-auto-commit-action/pull/75), [#73](https://github.com/stefanzweifel/git-auto-commit-action/pull/73)
 
+- Use `${{ github.head_ref }}` as default branch value. Therefore, the branch name when listening for `pull_request`-events is optional. [#75](https://github.com/stefanzweifel/git-auto-commit-action/pull/75), [#73](https://github.com/stefanzweifel/git-auto-commit-action/pull/73)
 
 ## [v4.1.6](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.5...v4.1.6) - 2020-04-28
 
 ### Fixes
+
 - Fix issue where tags could not be created correctly [#68](https://github.com/stefanzweifel/git-auto-commit-action/pull/68)
 
 ## [v4.1.5](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.4...v4.1.5) - 2020-04-23
 
 ### Added
+
 - Update `file_pattern` to support multiple file paths [#65](https://github.com/stefanzweifel/git-auto-commit-action/pull/65)
 
 ### Changes
+
 - Revert changes made in v4.1.4 [#63](https://github.com/stefanzweifel/git-auto-commit-action/pull/63)
 
 ### Fixes
+
 - Fix issue with `commit_options` [#64](https://github.com/stefanzweifel/git-auto-commit-action/pull/64)
 
 ## [v4.1.4](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.3...v4.1.4) - 2020-04-22
 
 ### Fixed
-- Fix bug introduced in previous version, where git user configuration has been placed inline [#62](https://github.com/stefanzweifel/git-auto-commit-action/pull/62)
 
+- Fix bug introduced in previous version, where git user configuration has been placed inline [#62](https://github.com/stefanzweifel/git-auto-commit-action/pull/62)
 
 ## [v4.1.3](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.2...v4.1.3) - 2020-04-18
 
 ### Changed
+
 - Place Git user configuration inline [#59](https://github.com/stefanzweifel/git-auto-commit-action/pull/59)
 
 ## [v4.1.2](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.1...v4.1.2) - 2020-04-03
 
 ### Fixes
+
 - Fix Issue with `changes_detected`-output [#57](https://github.com/stefanzweifel/git-auto-commit-action/pull/57)
 
 ## [v4.1.1](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.1.0...v4.1.1) - 2020-03-14
 
 ### Fixes
-- Fix issue where commit has not been pushed to remote repository, when no `branch`-option has been given [#54](https://github.com/stefanzweifel/git-auto-commit-action/pull/54)
 
+- Fix issue where commit has not been pushed to remote repository, when no `branch`-option has been given [#54](https://github.com/stefanzweifel/git-auto-commit-action/pull/54)
 
 ## [v4.1.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v4.0.0...v4.1.0) - 2020-03-05
 
 ### Added
+
 - Add `changes_detected` output [#49](https://github.com/stefanzweifel/git-auto-commit-action/pull/49), [#46](https://github.com/stefanzweifel/git-auto-commit-action/issues/46)
 - Add `tagging_message` input option to create and push tags [#50](https://github.com/stefanzweifel/git-auto-commit-action/pull/50), [#47](https://github.com/stefanzweifel/git-auto-commit-action/issues/47)
 
-
 ## [v4.0.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v3.0.0...v4.0.0) - 2020-02-24
 
 ### Changed
+
 - Switch Action to use `node12`-environment instead of `docker`. [#45](https://github.com/stefanzweifel/git-auto-commit-action/pull/45)
 
 ## [v3.0.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.5.0...v3.0.0) - 2020-02-06
 
 ### Added
+
 - Add `commit_user_name`, `commit_user_email` and `commit_author` input options for full customzation on how the commit is being created [#39](https://github.com/stefanzweifel/git-auto-commit-action/pull/39)
 
 ### Changed
+
 - Make the `branch` input option optional [#41](https://github.com/stefanzweifel/git-auto-commit-action/pull/41)
 
 ### Removed
-- Remove the need of a GITHUB_TOKEN. Users now have to use `actions/checkout@v2` or higher [#36](https://github.com/stefanzweifel/git-auto-commit-action/pull/36)
 
+- Remove the need of a GITHUB_TOKEN. Users now have to use `actions/checkout@v2` or higher [#36](https://github.com/stefanzweifel/git-auto-commit-action/pull/36)
 
 ## [v2.5.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.4.0...v2.5.0) - 2019-12-18
 
 ### Added
+
 - Add new `repository`-argument [#22](https://github.com/stefanzweifel/git-auto-commit-action/pull/22)
 
 ### Changed
-- Extract logic of the Action into methods and into a separate file [#24](https://github.com/stefanzweifel/git-auto-commit-action/pull/24)
 
+- Extract logic of the Action into methods and into a separate file [#24](https://github.com/stefanzweifel/git-auto-commit-action/pull/24)
 
 ## [v2.4.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.3.0...v2.4.0) - 2019-11-30
 
 ### Added
+
 - Commit untracked files [#19](https://github.com/stefanzweifel/git-auto-commit-action/pull/19) (fixes [#16](https://github.com/stefanzweifel/git-auto-commit-action/issues/16))
 - Add support for Git-LFS [#21](https://github.com/stefanzweifel/git-auto-commit-action/pull/21) (fixes [#20](https://github.com/stefanzweifel/git-auto-commit-action/issues/20))
 
-
 ## [v2.3.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.2.0...v2.3.0) - 2019-11-04
 
 ### Added
-- Add a new `commit_option`-argument. Allows users to define additional commit options for the `git-commit` command. [#14](https://github.com/stefanzweifel/git-auto-commit-action/pull/15)
 
+- Add a new `commit_option`-argument. Allows users to define additional commit options for the `git-commit` command. [#14](https://github.com/stefanzweifel/git-auto-commit-action/pull/15)
 
 ## [v2.2.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.1.0...v2.2.0) - 2019-10-26
 
 ### Added
-- Add new `file_pattern`-argument. Allows users to define which files should be added in the commit. [#13](https://github.com/stefanzweifel/git-auto-commit-action/pull/13)
 
+- Add new `file_pattern`-argument. Allows users to define which files should be added in the commit. [#13](https://github.com/stefanzweifel/git-auto-commit-action/pull/13)
 
 ## [v2.1.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v2.0.0...v2.1.0) - 2019-09-20
 
 ### Added
+
 - Add `branch`-argument to determine, to which branch changes should be pushed. See README for usage details.
 
 ### Fixed
+
 - Fixes Issue where changes couldn't be pushed to GitHub due to wrong ref-name.
 
 ### Removed
-- Remove `commit_author_email` and `commit_author_name` arguments. The `$GITHUB_ACTOR` is now used as the Git Author
 
+- Remove `commit_author_email` and `commit_author_name` arguments. The `$GITHUB_ACTOR` is now used as the Git Author
 
 ## [v2.0.0](https://github.com/stefanzweifel/git-auto-commit-action/compare/v1.0.0...v2.0.0) - 2019-08-31
 
 ### Changed
-- Make Action Compatible with latest beta of GitHub Actions [#3](https://github.com/stefanzweifel/git-auto-commit-action/pull/3)
 
+- Make Action Compatible with latest beta of GitHub Actions [#3](https://github.com/stefanzweifel/git-auto-commit-action/pull/3)
 
 ## v1.0.0 - 2019-06-10
 
 ### Added
 
 - Add Core Logic for Action
-

README.md

@@ -2,7 +2,6 @@
 
 > The GitHub Action for committing files for the 80% use case.
 
-<a href="https://github.com/search?o=desc&q=stefanzweifel%2Fgit-auto-commit-action+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%3Dstefanzweifel%2Fgit-auto-commit-action%26badge%3Dtrue" alt="Public workflows that use this action."></a>
 <a href="https://github.com/stefanzweifel/git-auto-commit-action/actions?query=workflow%3Atests">
     <img src="https://github.com/stefanzweifel/git-auto-commit-action/workflows/tests/badge.svg" alt="">
 </a>
@@ -28,15 +27,16 @@ The following is an extended example with all possible options available for thi
 ```yaml
 - uses: stefanzweifel/git-auto-commit-action@v4
   with:
-    # Optional, but recommended
+    # Optional. Commit message for the created commit.
     # Defaults to "Apply automatic changes"
     commit_message: Automated Change
 
-    # Optional branch name where commit should be pushed to.
-    # Defaults to the current branch.
+    # Optional. Local and remote branch name where commit is going to be pushed
+    #  to. Defaults to the current branch.
+    #  You might need to set `create_branch: true` if the branch does not exist.
     branch: feature-123
 
-    # Optional. Used by `git-commit`.
+    # Optional. Options used by `git-commit`.
     # See https://git-scm.com/docs/git-commit#_options
     commit_options: '--no-verify --signoff'
 
@@ -47,28 +47,28 @@ The following is an extended example with all possible options available for thi
     # - https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec
     file_pattern: src/*.js tests/*.js *.php
 
-    # Optional local file path to the repository
-    # Defaults to the root of the repository
+    # Optional. Local file path to the repository.
+    # Defaults to the root of the repository.
     repository: .
 
     # Optional commit user and author settings
-    commit_user_name: My GitHub Actions Bot # defaults to "GitHub Actions"
-    commit_user_email: my-github-actions-bot@example.org # defaults to "actions@github.com"
+    commit_user_name: My GitHub Actions Bot # defaults to "github-actions[bot]"
+    commit_user_email: my-github-actions-bot@example.org # defaults to "github-actions[bot]@users.noreply.github.com"
     commit_author: Author <actions@github.com> # defaults to author of the commit that triggered the run
 
-    # Optional tag message 
-    # Action will create and push a new tag to the remote repository and the defined branch
+    # Optional. Tag name being created in the local repository and 
+    # pushed to remtoe repository and defined branch.
     tagging_message: 'v1.0.0'
 
-    # Optional. Used by `git-status`
-    # See https://git-scm.com/docs/git-status#_options
+    # Optional. Option used by `git-status` to determine if the repository is 
+    # dirty. See https://git-scm.com/docs/git-status#_options
     status_options: '--untracked-files=no'
 
-    # Optional. Used by `git-add`
+    # Optional. Options used by `git-add`.
     # See https://git-scm.com/docs/git-add#_options
     add_options: '-u'
 
-    # Optional. Used by `git-push`
+    # Optional. Options used by `git-push`.
     # See https://git-scm.com/docs/git-push#_options
     push_options: '--force'
     
@@ -84,6 +84,9 @@ The following is an extended example with all possible options available for thi
     # Optional. Prevents the shell from expanding filenames. 
     # Details: https://www.gnu.org/software/bash/manual/html_node/Filename-Expansion.html
     disable_globbing: true
+
+    # Optional. Create given branch name in local and remote repository.
+    create_branch: true
 ```
 
 Please note that the Action depends on `bash`. If you're using the Action in a job in combination with a custom Docker container, make sure that `bash` is installed.
@@ -102,7 +105,7 @@ on:
   pull_request:
   push:
     branches:
-      - "main"
+      - main
 
 jobs:
   php-cs-fixer:
@@ -150,9 +153,9 @@ The goal of this Action is to be "the Action for committing files for the 80% us
 
 The following is a list of edge cases the Action knowingly does not support:
 
-**No `git pull` when the repository is out of the date with remote.** The will not do a `git pull` before doing the `git push`. **You** are responsible for keeping the repository up to date in your Workflow runs. 
+**No `git pull` when the repository is out of the date with remote.** The Action will not do a `git pull` before doing the `git push`. **You** are responsible for keeping the repository up to date in your Workflow runs. 
 
-**No support for running the Action in build matrices**. For example, if your Workflow is using build matrices, and you want that each job commits and pushes files to the remote, you will run into the issue, that the repository in the workflow will become out of date. As the Action will not do a `git pull` for you, you have to do that yourself.
+**No support for running the Action in build matrices**. If your Workflow is using build matrices, and you want that each job commits and pushes files to the remote, you will run into the issue, that the repository in the workflow will become out of date. As the Action will not do a `git pull` for you, you have to do that yourself.
 
 **No support for `git rebase` or `git merge`**. There are many strategies on how to integrate remote upstream changes to a local repository. `git-auto-commit` does not want to be responsible for doing that. 
 
@@ -160,8 +163,8 @@ If this Action doesn't work for your workflow, check out [EndBug/add-and-commit]
 
 ### Checkout the correct branch
 
-You must use `action/checkout@v2` or later versions to checkout the repository.
-In non-`push` events, such as `pull_request`, make sure to specify the `ref` to checkout:
+You must use `action/checkout@v2` or later versions to check out the repository.
+In non-`push` events, such as `pull_request`, make sure to specify the `ref` to check out:
 
 ```yaml
 - uses: actions/checkout@v2
@@ -169,12 +172,12 @@ In non-`push` events, such as `pull_request`, make sure to specify the `ref` to
     ref: ${{ github.head_ref }}
 ```
 
-You have to do this to avoid that the `checkout`-Action clones your repository in a detached state.
+Do this to avoid checking out the repository in a detached state.
 
 ### Commits made by this Action do not trigger new Workflow runs
 
 The resulting commit **will not trigger** another GitHub Actions Workflow run.
-This is due to [limitations set by GitHub](https://help.github.com/en/actions/reference/events-that-trigger-workflows#triggering-new-workflows-using-a-personal-access-token).
+This is due to [limitations set by GitHub](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
 
 > When you use the repository's GITHUB_TOKEN to perform tasks on behalf of the GitHub Actions app, events triggered by the GITHUB_TOKEN will not create a new workflow run. This prevents you from accidentally creating recursive workflow runs.
 
@@ -187,6 +190,8 @@ storing the token as a secret in your repository and then passing the new token
     token: ${{ secrets.PAT }}
 ```
 
+If you create a personal access token, apply the `repo` and `workflow` scopes.
+
 If you work in an organization and don't want to create a PAT from your personal account, we recommend using a [robot account](https://docs.github.com/en/github/getting-started-with-github/types-of-github-accounts) for the token.
 
 ## Advanced Uses
@@ -356,7 +361,7 @@ This is due to limitations set up by GitHub, [commits of this Action do not trig
 
 ## Running the tests
 
-The package has tests written in [bats](https://github.com/bats-core/bats-core). Before you can run the test suite locally, you have to install the dependencies with `npm` or `yarn`.
+The Action has tests written in [bats](https://github.com/bats-core/bats-core). Before you can run the test suite locally, you have to install the dependencies with `npm` or `yarn`.
 
 ```shell
 npm install

action.yml

@@ -25,7 +25,7 @@ inputs:
     required: false
     default: ''
   file_pattern:
-    description: File pattern used for `git add`. For example `src/\*.js`
+    description: File pattern used for `git add`. For example `src/*.js`
     required: false
     default: '.'
   repository:
@@ -35,11 +35,11 @@ inputs:
   commit_user_name:
     description: Name used for the commit user
     required: false
-    default: GitHub Actions
+    default: github-actions[bot]
   commit_user_email:
     description: Email address used for the commit user
     required: false
-    default: actions@github.com
+    default: github-actions[bot]@users.noreply.github.com
   commit_author:
     description: Value used for the commit author. Defaults to the username of whoever triggered this workflow run.
     required: false
@@ -67,6 +67,9 @@ inputs:
   disable_globbing:
     description: Stop the shell from expanding filenames (https://www.gnu.org/software/bash/manual/html_node/Filename-Expansion.html)
     default: false
+  create_branch:
+    description: Create new branch with the name of `branch`-input in local and remote repository, if it doesn't exist yet.
+    default: false
 
 outputs:
   changes_detected:

entrypoint.sh

@@ -47,20 +47,26 @@ _git_is_dirty() {
 _switch_to_branch() {
     echo "INPUT_BRANCH value: $INPUT_BRANCH";
 
-    # Fetch remote to make sure that repo can be switched to the right branch.
-
+    # Fetch remote to make sure that repo can be switched to the right branch.
     if "$INPUT_SKIP_FETCH"; then
         echo "::debug::git-fetch has not been executed";
     else
         git fetch --depth=1;
     fi
 
+    # If `skip_checkout`-input is true, skip the entire checkout step.
     if "$INPUT_SKIP_CHECKOUT"; then
         echo "::debug::git-checkout has not been executed";
     else
-        # Switch to branch from current Workflow run
-        # shellcheck disable=SC2086
-        git checkout $INPUT_BRANCH;
+        # Create new local branch if `create_branch`-input is true
+        if "$INPUT_CREATE_BRANCH"; then
+            # shellcheck disable=SC2086
+            git checkout -B $INPUT_BRANCH --;
+        else
+            # Switch to branch from current Workflow run
+            # shellcheck disable=SC2086
+            git checkout $INPUT_BRANCH --;
+        fi
     fi
 }
 

tests/git-auto-commit.bats

@@ -26,6 +26,7 @@ setup() {
     export INPUT_SKIP_FETCH=false
     export INPUT_SKIP_CHECKOUT=false
     export INPUT_DISABLE_GLOBBING=false
+    export INPUT_CREATE_BRANCH=false
 
     # Configure Git
     if [[ -z $(git config user.name) ]]; then
@@ -185,7 +186,10 @@ git_auto_commit() {
 }
 
 @test "It applies INPUT_FILE_PATTERN when creating commit" {
-    INPUT_FILE_PATTERN="*.txt *.html"
+    INPUT_FILE_PATTERN="src/*.js *.txt *.html"
+
+    mkdir src;
+    touch src/new-file-{1,2}.js;
 
     touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2}.php
     touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2}.html
@@ -194,7 +198,7 @@ git_auto_commit() {
 
     assert_success
 
-    assert_line "INPUT_FILE_PATTERN: *.txt *.html"
+    assert_line "INPUT_FILE_PATTERN: src/*.js *.txt *.html"
     assert_line "::debug::Push commit to remote branch master"
 
     # Assert that PHP files have not been added.
@@ -507,3 +511,285 @@ git_auto_commit() {
     run git status
     assert_output --partial 'nothing to commit, working tree clean'
 }
+
+@test "It does not throw an error if branch is checked out with same name as a file or folder in the repo" {
+
+    # Add File called dev and commit/push
+    echo "Create dev file";
+    cd "${FAKE_LOCAL_REPOSITORY}";
+    echo this is a file named dev > dev
+    git add dev
+    git commit -m 'add file named dev'
+    git update-ref refs/remotes/origin/master master
+    git update-ref refs/remotes/origin/dev master
+
+    # ---
+
+    INPUT_BRANCH=dev
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{4,5,6}.txt
+
+    run git_auto_commit
+
+    assert_success
+
+    assert_line "INPUT_REPOSITORY value: ${INPUT_REPOSITORY}"
+    assert_line "::set-output name=changes_detected::true"
+    assert_line "::debug::Push commit to remote branch dev"
+}
+
+@test "script fails to push commit to new branch that does not exist yet" {
+    INPUT_BRANCH="not-existend-branch"
+    INPUT_CREATE_BRANCH=false
+
+    run git branch
+    refute_line --partial "not-existend-branch"
+
+    run git branch -r
+    refute_line --partial "origin/not-existend-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_failure
+
+    assert_line "INPUT_REPOSITORY value: ${INPUT_REPOSITORY}"
+    assert_line "::set-output name=changes_detected::true"
+    assert_line "INPUT_BRANCH value: not-existend-branch"
+    assert_line "fatal: invalid reference: not-existend-branch"
+
+    run git branch
+    refute_line --partial "not-existend-branch"
+
+    run git branch -r
+    refute_line --partial "origin/not-existend-branch"
+}
+
+@test "It creates new local branch and pushes the new branch to remote" {
+    INPUT_BRANCH="not-existend-branch"
+    INPUT_CREATE_BRANCH=true
+
+    run git branch
+    refute_line --partial "not-existend-branch"
+
+    run git branch -r
+    refute_line --partial "origin/not-existend-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_success
+
+    assert_line "INPUT_REPOSITORY value: ${INPUT_REPOSITORY}"
+    assert_line "::set-output name=changes_detected::true"
+    assert_line -e "::set-output name=commit_hash::[0-9a-f]{40}$"
+    assert_line "INPUT_BRANCH value: not-existend-branch"
+    assert_line "INPUT_FILE_PATTERN: ."
+    assert_line "INPUT_COMMIT_OPTIONS: "
+    assert_line "::debug::Apply commit options "
+    assert_line "INPUT_TAGGING_MESSAGE: "
+    assert_line "No tagging message supplied. No tag will be added."
+    assert_line "INPUT_PUSH_OPTIONS: "
+    assert_line "::debug::Apply push options "
+    assert_line "::debug::Push commit to remote branch not-existend-branch"
+
+    run git branch
+    assert_line --partial "not-existend-branch"
+
+    run git branch -r
+    assert_line --partial "origin/not-existend-branch"
+}
+
+@test "it does not create new local branch if local branch already exists" {
+
+    git checkout -b not-existend-remote-branch
+    git checkout master
+
+    INPUT_BRANCH="not-existend-remote-branch"
+    INPUT_CREATE_BRANCH=true
+
+    run git branch
+    assert_line --partial "not-existend-remote-branch"
+
+    run git branch -r
+    refute_line --partial "origin/not-existend-remote-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_success
+
+    assert_line "INPUT_REPOSITORY value: ${INPUT_REPOSITORY}"
+    assert_line "::set-output name=changes_detected::true"
+    assert_line -e "::set-output name=commit_hash::[0-9a-f]{40}$"
+    assert_line "INPUT_BRANCH value: not-existend-remote-branch"
+    assert_line "INPUT_FILE_PATTERN: ."
+    assert_line "INPUT_COMMIT_OPTIONS: "
+    assert_line "::debug::Apply commit options "
+    assert_line "INPUT_TAGGING_MESSAGE: "
+    assert_line "No tagging message supplied. No tag will be added."
+    assert_line "INPUT_PUSH_OPTIONS: "
+    assert_line "::debug::Apply push options "
+    assert_line "::debug::Push commit to remote branch not-existend-remote-branch"
+
+    run git branch
+    assert_line --partial "not-existend-remote-branch"
+
+    run git branch -r
+    assert_line --partial "origin/not-existend-remote-branch"
+}
+
+@test "it creates new local branch and pushes branch to remote even if the remote branch already exists" {
+
+    # Create `existing-remote-branch` on remote with changes the local repository does not yet have
+    cd $FAKE_TEMP_LOCAL_REPOSITORY;
+    git checkout -b "existing-remote-branch"
+    touch new-branch-file.txt
+    git add new-branch-file.txt
+    git commit -m "Add additional file";
+    git push origin existing-remote-branch;
+
+    run git branch;
+    assert_line --partial "existing-remote-branch"
+
+    # ---------
+    # Switch to our regular local repository and run `git-auto-commit`
+    cd $FAKE_LOCAL_REPOSITORY;
+
+    INPUT_BRANCH="existing-remote-branch"
+    INPUT_CREATE_BRANCH=true
+
+    run git branch
+    refute_line --partial "existing-remote-branch"
+
+    run git fetch --all;
+    run git pull origin existing-remote-branch;
+    run git branch -r;
+    assert_line --partial "origin/existing-remote-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_success
+
+    assert_line "INPUT_REPOSITORY value: ${INPUT_REPOSITORY}"
+    assert_line "::set-output name=changes_detected::true"
+    assert_line -e "::set-output name=commit_hash::[0-9a-f]{40}$"
+    assert_line "INPUT_BRANCH value: existing-remote-branch"
+    assert_line "INPUT_FILE_PATTERN: ."
+    assert_line "INPUT_COMMIT_OPTIONS: "
+    assert_line "::debug::Apply commit options "
+    assert_line "INPUT_TAGGING_MESSAGE: "
+    assert_line "No tagging message supplied. No tag will be added."
+    assert_line "INPUT_PUSH_OPTIONS: "
+    assert_line "::debug::Apply push options "
+    assert_line "::debug::Push commit to remote branch existing-remote-branch"
+
+    run git branch
+    assert_line --partial "existing-remote-branch"
+
+    run git branch -r
+    assert_line --partial "origin/existing-remote-branch"
+
+    # Assert that branch "existing-remote-branch" was updated on remote
+    current_sha="$(git rev-parse --verify --short existing-remote-branch)"
+    remote_sha="$(git rev-parse --verify --short origin/existing-remote-branch)"
+
+    assert_equal $current_sha $remote_sha;
+}
+
+@test "script fails if new local branch is checked out and push fails as remote has newer commits than local" {
+    # Create `existing-remote-branch` on remote with changes the local repository does not yet have
+    cd $FAKE_TEMP_LOCAL_REPOSITORY;
+    git checkout -b "existing-remote-branch"
+    touch new-branch-file.txt
+    git add new-branch-file.txt
+    git commit -m "Add additional file";
+    git push origin existing-remote-branch;
+
+    run git branch;
+    assert_line --partial "existing-remote-branch"
+
+    # ---------
+    # Switch to our regular local repository and run `git-auto-commit`
+    cd $FAKE_LOCAL_REPOSITORY;
+
+    INPUT_BRANCH="existing-remote-branch"
+    INPUT_CREATE_BRANCH=true
+
+    run git branch
+    refute_line --partial "existing-remote-branch"
+
+    run git fetch --all;
+    run git branch -r;
+    assert_line --partial "origin/existing-remote-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_failure
+
+    assert_line "hint: Updates were rejected because the tip of your current branch is behind"
+
+    # Assert that branch exists locally and on remote
+    run git branch
+    assert_line --partial "existing-remote-branch"
+
+    run git branch -r
+    assert_line --partial "origin/existing-remote-branch"
+
+    # Assert that branch "existing-remote-branch" was not updated on remote
+    current_sha="$(git rev-parse --verify --short existing-remote-branch)"
+    remote_sha="$(git rev-parse --verify --short origin/existing-remote-branch)"
+
+    refute [assert_equal $current_sha $remote_sha];
+}
+
+@test "It pushes commit to remote if branch already exists and local repo is behind its remote counterpart" {
+    # Create `new-branch` on remote with changes the local repository does not yet have
+    cd $FAKE_TEMP_LOCAL_REPOSITORY;
+
+    git checkout -b "new-branch"
+    touch new-branch-file.txt
+    git add new-branch-file.txt
+
+    git commit --quiet -m "Add additional file";
+    git push origin new-branch;
+
+    run git branch -r
+    assert_line --partial "origin/new-branch"
+
+    # ---------
+    # Switch to our regular local repository and run `git-auto-commit`
+    cd $FAKE_LOCAL_REPOSITORY;
+
+    INPUT_BRANCH="new-branch"
+
+    # Assert that local remote does not know have "new-branch" locally nor does
+    # know about the remote branch.
+    run git branch
+    refute_line --partial "new-branch"
+
+    run git branch -r
+    refute_line --partial "origin/new-branch"
+
+    touch "${FAKE_LOCAL_REPOSITORY}"/new-file-{1,2,3}.txt
+
+    run git_auto_commit
+
+    assert_success
+
+    assert_line "INPUT_BRANCH value: new-branch"
+    assert_line --partial "::debug::Push commit to remote branch new-branch"
+
+    # Assert that branch "new-branch" was updated on remote
+    current_sha="$(git rev-parse --verify --short new-branch)"
+    remote_sha="$(git rev-parse --verify --short origin/new-branch)"
+
+    assert_equal $current_sha $remote_sha;
+}