[![Public workflows that use this action.](https://img.shields.io/endpoint?style=for-the-badge\&url=https%3A%2F%2Fused-by.vercel.app%2Fapi%2Fgithub-actions%2Fused-by%3Faction%3Dtj-actions%2Fchanged-files%26badge%3Dtrue)](https://github.com/search?o=desc\&q=tj-actions+changed-files+language%3AYAML\&s=\&type=Code)
Effortlessly track all changed files and directories relative to a target branch, preceding commit or the last remote commit returning **relative paths** from the project root using this GitHub action.
* Leverages either [Github's REST API](https://docs.github.com/en/rest/reference/repos#list-commits) or [Git's native diff](https://git-scm.com/docs/git-diff) to determine changed files.
* Generates escaped [JSON output for running matrix jobs](https://github.com/tj-actions/changed-files/blob/main/.github/workflows/matrix-test.yml) based on changed files.
> * For `push` events: When configuring [`actions/checkout`](https://github.com/actions/checkout#usage), make sure to set [`fetch-depth`](https://github.com/actions/checkout#usage) to either `0` or `2`, depending on your use case.
> * For mono repositories where pulling all branch history might not be desired, you can still use the default [`fetch-depth`](https://github.com/actions/checkout#usage), which is set to `1` for `pull_request` events.
> * Avoid using single or double quotes for multiline inputs, as the value is already a string separated by a newline character. See [Examples](#examples) for more information.
> * If [`fetch-depth`](https://github.com/actions/checkout#usage) isn't set to `0`, ensure that `persist-credentials` is set to `true` when configuring [`actions/checkout`](https://github.com/actions/checkout#usage).
> * For repositories that have PRs generated from forks, when configuring [`actions/checkout`](https://github.com/actions/checkout#usage), set the [`repository`](https://github.com/actions/checkout#usage) to `${{ github.event.pull_request.head.repo.full_name }}`. See [Example](https://github.com/tj-actions/changed-files/blob/main/.github/workflows/test.yml#L49-L53).
Visit the [discussions for more information](https://github.com/tj-actions/changed-files/discussions) or [create a new discussion](https://github.com/tj-actions/changed-files/discussions/new/choose) for usage-related questions.
# NOTE: Ensure all outputs are prefixed by the same key used above e.g. `test_(...)` | `doc_(...)` | `src_(...)` when trying to access the `any_changed` output.
| <aname="output_added_files"></a>[added\_files](#output_added_files) | string | Returns only files that are <br>Added (A). |
| <aname="output_added_files_count"></a>[added\_files\_count](#output_added_files_count) | string | Returns the number of `added_files` |
| <aname="output_all_changed_and_modified_files"></a>[all\_changed\_and\_modified\_files](#output_all_changed_and_modified_files) | string | Returns all changed and modified <br>files i.e. *a combination of (ACMRDTUX)* |
| <aname="output_all_changed_and_modified_files_count"></a>[all\_changed\_and\_modified\_files\_count](#output_all_changed_and_modified_files_count) | string | Returns the number of `all_changed_and_modified_files` |
| <aname="output_all_changed_files"></a>[all\_changed\_files](#output_all_changed_files) | string | Returns all changed files i.e. <br>*a combination of all added, copied, modified and renamed files (ACMR)* |
| <aname="output_all_changed_files_count"></a>[all\_changed\_files\_count](#output_all_changed_files_count) | string | Returns the number of `all_changed_files` |
| <aname="output_all_modified_files"></a>[all\_modified\_files](#output_all_modified_files) | string | Returns all changed files i.e. <br>*a combination of all added, copied, modified, renamed and deleted files (ACMRD)*. |
| <aname="output_all_modified_files_count"></a>[all\_modified\_files\_count](#output_all_modified_files_count) | string | Returns the number of `all_modified_files` |
| <aname="output_all_old_new_renamed_files"></a>[all\_old\_new\_renamed\_files](#output_all_old_new_renamed_files) | string | Returns only files that are <br>Renamed and lists their old <br>and new names. **NOTE:** This <br>requires setting `include_all_old_new_renamed_files` to `true`. <br>Also, keep in mind that <br>this output is global and <br>wouldn't be nested in outputs <br>generated when the `*_yaml_*` input <br>is used. (R) |
| <aname="output_all_old_new_renamed_files_count"></a>[all\_old\_new\_renamed\_files\_count](#output_all_old_new_renamed_files_count) | string | Returns the number of `all_old_new_renamed_files` |
| <aname="output_any_changed"></a>[any\_changed](#output_any_changed) | string | Returns `true` when any of <br>the filenames provided using the <br>`files*` or `files_ignore*` inputs has changed. i.e. <br>*includes a combination of all added, copied, modified and renamed files (ACMR)*. |
| <aname="output_any_deleted"></a>[any\_deleted](#output_any_deleted) | string | Returns `true` when any of <br>the filenames provided using the <br>`files*` or `files_ignore*` inputs has been deleted. <br>(D) |
| <aname="output_any_modified"></a>[any\_modified](#output_any_modified) | string | Returns `true` when any of <br>the filenames provided using the <br>`files*` or `files_ignore*` inputs has been modified. <br>i.e. *includes a combination of all added, copied, modified, renamed, and deleted files (ACMRD)*. |
| <aname="output_changed_keys"></a>[changed\_keys](#output_changed_keys) | string | Returns all changed YAML keys <br>when the `files_yaml` input is <br>used. i.e. *key that contains any path that has either been added, copied, modified, and renamed (ACMR)* |
| <aname="output_modified_keys"></a>[modified\_keys](#output_modified_keys) | string | Returns all modified YAML keys <br>when the `files_yaml` input is <br>used. i.e. *key that contains any path that has either been added, copied, modified, and deleted (ACMRD)* |
| <aname="output_only_changed"></a>[only\_changed](#output_only_changed) | string | Returns `true` when only files <br>provided using the `files*` or `files_ignore*` inputs <br>has changed. i.e. *includes a combination of all added, copied, modified and renamed files (ACMR)*. |
| <aname="output_only_deleted"></a>[only\_deleted](#output_only_deleted) | string | Returns `true` when only files <br>provided using the `files*` or `files_ignore*` inputs <br>has been deleted. (D) |
| <aname="output_only_modified"></a>[only\_modified](#output_only_modified) | string | Returns `true` when only files <br>provided using the `files*` or `files_ignore*` inputs <br>has been modified. (ACMRD). |
| <aname="output_other_changed_files"></a>[other\_changed\_files](#output_other_changed_files) | string | Returns all other changed files <br>not listed in the files <br>input i.e. *includes a combination of all added, copied, modified and renamed files (ACMR)*. |
| <aname="output_other_changed_files_count"></a>[other\_changed\_files\_count](#output_other_changed_files_count) | string | Returns the number of `other_changed_files` |
| <aname="output_other_deleted_files"></a>[other\_deleted\_files](#output_other_deleted_files) | string | Returns all other deleted files <br>not listed in the files <br>input i.e. *a combination of all deleted files (D)* |
| <aname="output_other_deleted_files_count"></a>[other\_deleted\_files\_count](#output_other_deleted_files_count) | string | Returns the number of `other_deleted_files` |
| <aname="output_other_modified_files"></a>[other\_modified\_files](#output_other_modified_files) | string | Returns all other modified files <br>not listed in the files <br>input i.e. *a combination of all added, copied, modified, and deleted files (ACMRD)* |
| <aname="output_other_modified_files_count"></a>[other\_modified\_files\_count](#output_other_modified_files_count) | string | Returns the number of `other_modified_files` |
| <aname="output_renamed_files"></a>[renamed\_files](#output_renamed_files) | string | Returns only files that are <br>Renamed (R). |
| <aname="output_renamed_files_count"></a>[renamed\_files\_count](#output_renamed_files_count) | string | Returns the number of `renamed_files` |
| <aname="output_type_changed_files"></a>[type\_changed\_files](#output_type_changed_files) | string | Returns only files that have <br>their file type changed (T). |
| <aname="output_type_changed_files_count"></a>[type\_changed\_files\_count](#output_type_changed_files_count) | string | Returns the number of `type_changed_files` |
| <aname="output_unknown_files"></a>[unknown\_files](#output_unknown_files) | string | Returns only files that are <br>Unknown (X). |
| <aname="output_unknown_files_count"></a>[unknown\_files\_count](#output_unknown_files_count) | string | Returns the number of `unknown_files` |
| <aname="output_unmerged_files"></a>[unmerged\_files](#output_unmerged_files) | string | Returns only files that are <br>Unmerged (U). |
| <aname="output_unmerged_files_count"></a>[unmerged\_files\_count](#output_unmerged_files_count) | string | Returns the number of `unmerged_files` |
| <aname="input_base_sha"></a>[base\_sha](#input_base_sha) | string | false | | Specify a different base commit <br>SHA used for comparing changes |
| <aname="input_diff_relative"></a>[diff\_relative](#input_diff_relative) | string | false | `"true"` | Exclude changes outside the current <br>directory and show path names <br>relative to it. **NOTE:** This <br>requires you to specify the <br>top level directory via the <br>`path` input. |
| <aname="input_dir_names"></a>[dir\_names](#input_dir_names) | string | false | `"false"` | Output unique changed directories instead <br>of filenames. **NOTE:** This returns <br>`.` for changed files located <br>in the current working directory <br>which defaults to `$GITHUB_WORKSPACE`. |
| <aname="input_dir_names_deleted_files_include_only_deleted_dirs"></a>[dir\_names\_deleted\_files\_include\_only\_deleted\_dirs](#input_dir_names_deleted_files_include_only_deleted_dirs) | string | false | `"false"` | Include only directories that have <br>been deleted as opposed to <br>directory names of files that <br>have been deleted in the <br>`deleted_files` output when `dir_names` is <br>set to `true`. |
| <aname="input_dir_names_exclude_current_dir"></a>[dir\_names\_exclude\_current\_dir](#input_dir_names_exclude_current_dir) | string | false | `"false"` | Exclude the current directory represented <br>by `.` from the output <br>when `dir_names` is set to <br>`true`. |
| <aname="input_dir_names_include_files"></a>[dir\_names\_include\_files](#input_dir_names_include_files) | string | false | | Include files in the output <br>when `dir_names` is set to <br>`true`. **NOTE:** This returns only <br>the matching files and also <br>the directory names. |
| <aname="input_dir_names_include_files_separator"></a>[dir\_names\_include\_files\_separator](#input_dir_names_include_files_separator) | string | false | `"\n"` | Separator used to split the <br>`dir_names_include_files` input |
| <aname="input_dir_names_max_depth"></a>[dir\_names\_max\_depth](#input_dir_names_max_depth) | string | false | | Limit the directory output to <br>a maximum depth e.g `test/test1/test2`<br>with max depth of `2`<br>returns `test/test1`. |
| <aname="input_fail_on_initial_diff_error"></a>[fail\_on\_initial\_diff\_error](#input_fail_on_initial_diff_error) | string | false | `"false"` | Fail when the initial diff <br>fails. |
| <aname="input_fail_on_submodule_diff_error"></a>[fail\_on\_submodule\_diff\_error](#input_fail_on_submodule_diff_error) | string | false | `"false"` | Fail when the submodule diff <br>fails. |
| <aname="input_fetch_additional_submodule_history"></a>[fetch\_additional\_submodule\_history](#input_fetch_additional_submodule_history) | string | false | `"false"` | Fetch additional history for submodules. |
| <aname="input_fetch_depth"></a>[fetch\_depth](#input_fetch_depth) | string | false | `"50"` | Depth of additional branch history <br>fetched. **NOTE**: This can be <br>adjusted to resolve errors with <br>insufficient history. |
| <aname="input_files"></a>[files](#input_files) | string | false | | File and directory patterns used <br>to detect changes (Defaults to the entire repo if unset) **NOTE:**<br>Multiline file/directory patterns should not <br>include quotes. |
| <aname="input_files_from_source_file"></a>[files\_from\_source\_file](#input_files_from_source_file) | string | false | | Source file(s) used to populate <br>the `files` input. |
| <aname="input_files_from_source_file_separator"></a>[files\_from\_source\_file\_separator](#input_files_from_source_file_separator) | string | false | `"\n"` | Separator used to split the <br>`files_from_source_file` input |
| <aname="input_files_ignore"></a>[files\_ignore](#input_files_ignore) | string | false | | Ignore changes to these file(s) <br>**NOTE:** Multiline file/directory patterns should <br>not include quotes. |
| <aname="input_files_ignore_from_source_file"></a>[files\_ignore\_from\_source\_file](#input_files_ignore_from_source_file) | string | false | | Source file(s) used to populate <br>the `files_ignore` input |
| <aname="input_files_ignore_from_source_file_separator"></a>[files\_ignore\_from\_source\_file\_separator](#input_files_ignore_from_source_file_separator) | string | false | `"\n"` | Separator used to split the <br>`files_ignore_from_source_file` input |
| <aname="input_files_ignore_separator"></a>[files\_ignore\_separator](#input_files_ignore_separator) | string | false | `"\n"` | Separator used to split the <br>`files_ignore` input |
| <aname="input_files_ignore_yaml"></a>[files\_ignore\_yaml](#input_files_ignore_yaml) | string | false | | YAML used to define a <br>set of file patterns to <br>ignore changes |
| <aname="input_files_ignore_yaml_from_source_file"></a>[files\_ignore\_yaml\_from\_source\_file](#input_files_ignore_yaml_from_source_file) | string | false | | Source file(s) used to populate <br>the `files_ignore_yaml` input. [Example](https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml) |
| <aname="input_files_ignore_yaml_from_source_file_separator"></a>[files\_ignore\_yaml\_from\_source\_file\_separator](#input_files_ignore_yaml_from_source_file_separator) | string | false | `"\n"` | Separator used to split the <br>`files_ignore_yaml_from_source_file` input |
| <aname="input_files_separator"></a>[files\_separator](#input_files_separator) | string | false | `"\n"` | Separator used to split the <br>`files` input |
| <aname="input_files_yaml"></a>[files\_yaml](#input_files_yaml) | string | false | | YAML used to define a <br>set of file patterns to <br>detect changes |
| <aname="input_files_yaml_from_source_file"></a>[files\_yaml\_from\_source\_file](#input_files_yaml_from_source_file) | string | false | | Source file(s) used to populate <br>the `files_yaml` input. [Example](https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml) |
| <aname="input_files_yaml_from_source_file_separator"></a>[files\_yaml\_from\_source\_file\_separator](#input_files_yaml_from_source_file_separator) | string | false | `"\n"` | Separator used to split the <br>`files_yaml_from_source_file` input |
| <aname="input_include_all_old_new_renamed_files"></a>[include\_all\_old\_new\_renamed\_files](#input_include_all_old_new_renamed_files) | string | false | `"false"` | Include `all_old_new_renamed_files` output. Note this <br>can generate a large output <br>See: [#501](https://github.com/tj-actions/changed-files/issues/501). |
| <aname="input_json"></a>[json](#input_json) | string | false | `"false"` | Output list of changed files <br>in a JSON formatted string <br>which can be used for <br>matrix jobs. [Example](https://github.com/tj-actions/changed-files/blob/main/.github/workflows/matrix-test.yml) |
| <aname="input_old_new_files_separator"></a>[old\_new\_files\_separator](#input_old_new_files_separator) | string | false | `" "` | Split character for old and <br>new renamed filename pairs. |
| <aname="input_old_new_separator"></a>[old\_new\_separator](#input_old_new_separator) | string | false | `","` | Split character for old and <br>new filename pairs. |
| <aname="input_output_dir"></a>[output\_dir](#input_output_dir) | string | false | `".github/outputs"` | Directory to store output files. |
| <aname="input_path"></a>[path](#input_path) | string | false | `"."` | Specify a relative path under <br>`$GITHUB_WORKSPACE` to locate the repository. |
| <aname="input_quotepath"></a>[quotepath](#input_quotepath) | string | false | `"true"` | Use non-ascii characters to match <br>files and output the filenames <br>completely verbatim by setting this <br>to `false` |
| <aname="input_recover_deleted_files_to_destination"></a>[recover\_deleted\_files\_to\_destination](#input_recover_deleted_files_to_destination) | string | false | | Recover deleted files to a <br>new destination directory, defaults to <br>the original location. |
| <aname="input_recover_files"></a>[recover\_files](#input_recover_files) | string | false | | File and directory patterns used <br>to recover deleted files, defaults <br>to the patterns provided via <br>the `files`, `files_from_source_file`, `files_ignore` and <br>`files_ignore_from_source_file` inputs or all deleted <br>files if no patterns are <br>provided. |
| <aname="input_recover_files_ignore"></a>[recover\_files\_ignore](#input_recover_files_ignore) | string | false | | File and directory patterns to <br>ignore when recovering deleted files. |
| <aname="input_recover_files_ignore_separator"></a>[recover\_files\_ignore\_separator](#input_recover_files_ignore_separator) | string | false | `"\n"` | Separator used to split the <br>`recover_files_ignore` input |
| <aname="input_recover_files_separator"></a>[recover\_files\_separator](#input_recover_files_separator) | string | false | `"\n"` | Separator used to split the <br>`recover_files` input |
| <aname="input_separator"></a>[separator](#input_separator) | string | false | `" "` | Split character for output strings |
| <aname="input_sha"></a>[sha](#input_sha) | string | false | | Specify a different commit SHA <br>used for comparing changes |
| <aname="input_since"></a>[since](#input_since) | string | false | | Get changed files for commits <br>whose timestamp is older than <br>the given time. |
| <aname="input_since_last_remote_commit"></a>[since\_last\_remote\_commit](#input_since_last_remote_commit) | string | false | `"false"` | Use the last commit on <br>the remote branch as the <br>`base_sha`. Defaults to the last <br>non-merge commit on the target <br>branch for pull request events <br>and the previous remote commit <br>of the current branch for <br>push events. |
| <aname="input_skip_initial_fetch"></a>[skip\_initial\_fetch](#input_skip_initial_fetch) | string | false | `"false"` | Skip the initial fetch to <br>improve performance for shallow repositories. <br>**NOTE**: This could lead to <br>errors with missing history and <br>the intended use is limited <br>to when you've fetched the <br>history necessary to perform the <br>diff. |
| <aname="input_token"></a>[token](#input_token) | string | false | `"${{ github.token }}"` | Github token used to fetch <br>changed files from Github's API. |
| <aname="input_until"></a>[until](#input_until) | string | false | | Get changed files for commits <br>whose timestamp is earlier than <br>the given time. |
| <aname="input_write_output_files"></a>[write\_output\_files](#input_write_output_files) | string | false | `"false"` | Write outputs to the `output_dir`<br>defaults to `.github/outputs` folder. **NOTE:**<br>This creates a `.txt` file <br>by default and a `.json`<br>file if `json` is set <br>to `true`. |
* [coder/code-server: uses tj-actions/changed-files to automate detecting changes and run steps based on the outcome](https://github.com/coder/code-server/blob/c32a31d802f679846876b8ad9aacff6cf7b5361d/.github/workflows/build.yaml#L48)
* [tldr-pages/tldr: uses tj-actions/changed-files to automate detecting spelling errors](https://github.com/tldr-pages/tldr/blob/main/.github/workflows/codespell.yml#L14)
* [nodejs/docker-node: uses tj-actions/changed-files to generate matrix jobs based on changes detected](https://github.com/nodejs/docker-node/blob/3c4fa6daf06a4786d202f2f610351837806a0380/.github/workflows/build-test.yml#L29)
* [refined-github: uses tj-actions/changed-files to automate test URL validation in added/edited files](https://github.com/refined-github/refined-github/blob/b754bfe58904da8a599d7876fdaaf18302785629/.github/workflows/features.yml#L35)
* [aws-doc-sdk-examples: uses tj-actions/changed-files to automate testing](https://github.com/awsdocs/aws-doc-sdk-examples/blob/2393723ef6b0cad9502f4852f5c72f7be58ca89d/.github/workflows/javascript.yml#L22)
* [nhost: uses tj-actions/changed-files to automate testing based on changes detected](https://github.com/nhost/nhost/blob/main/.github/workflows/ci.yaml#L44-L48)
* [qmk\_firmware uses tj-actions/changed-files to run linters](https://github.com/qmk/qmk_firmware/blob/7a737235ffd49c32d2c5561e8fe53fd96baa7f96/.github/workflows/lint.yml#L30)
With the switch from using grep's Extended regex to match files to the natively supported workflow glob pattern matching syntax introduced in [v13](https://github.com/tj-actions/changed-files/releases/tag/v13) you'll need to modify patterns used to match `files`.
* Any details about your workflow that might be helpful in troubleshooting. (**NOTE**: Ensure that you include full log outputs with debugging enabled)