changed-files

## changed-files Effortlessly track all changed files and directories relative to a target branch, the current branch (preceding commit or the last remote commit), multiple branches, or custom commits returning **relative paths** from the project root using this GitHub action. > \[!NOTE] > > * This action solely identifies files that have changed for events such as [`pull_request*`, `push`, `merge_group`, `release`, and many more](#other-supported-events-electron). However, it doesn't detect pending uncommitted changes created during the workflow execution. > > See: https://github.com/tj-actions/verify-changed-files instead. ## Table of contents * [Features ](#features-) * [Usage ](#usage-) * [On `pull_request` ](#on-pull_request-) * [Using local .git directory ](#using-local-git-directory-) * [Using Github's API :octocat:](#using-githubs-api-octocat) * [On `push` ⬆️](#on-push-️) * [Other supported events :electron:](#other-supported-events-electron) * [Inputs ⚙️](#inputs-️) * [Useful Acronyms ](#useful-acronyms-) * [Outputs ](#outputs-) * [Versioning ️](#versioning-️) * [Examples ](#examples-) * [Real-world usage ](#real-world-usage-) * [Open source projects ](#open-source-projects-) * [Scalability Example ](#scalability-example-) * [Important Notice ⚠️](#important-notice-️) * [Migration guide ](#migration-guide-) * [Credits ](#credits-) * [Report Bugs ](#report-bugs-) * [Contributors ✨](#contributors-) * [ Automate Your Job Search Too](#-automate-your-job-search-too) ## Features * Fast execution, averaging 0-10 seconds. * Leverages either [Github's REST API](https://docs.github.com/en/rest/reference/repos#list-commits) or [Git's native diff command](https://git-scm.com/docs/git-diff) to determine changed files. * Facilitates easy debugging. * Scales to handle large/mono repositories. * Supports Git submodules. * Supports [merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) for pull requests. * Generates escaped [JSON output for running matrix jobs](https://github.com/tj-actions/changed-files/blob/main/.github/workflows/matrix-example.yml) based on changed files. * Lists changed directories. * Limits matching changed directories to a specified maximum depth. * Optionally excludes the current directory. * Writes outputs to a designated `.txt` or `.json` file for further processing. * Restores deleted files to their previous location or a newly specified location. * Supports fetching a fixed number of commits, which improves performance. * Compatible with all platforms (Linux, MacOS, Windows). * Supports [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). * Supports [GitHub Enterprise Server](https://docs.github.com/en/[email protected]/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). * Supports [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners). * Lists all files and directories that have changed: * Between the current pull request branch and the last commit on the target branch. * Between the last commit and the current pushed change. * Between the last remote branch commit and the current HEAD. * Restricts change detection to a subset of files and directories: * Provides boolean output indicating changes in specific files. * Uses [Glob pattern](https://en.wikipedia.org/wiki/Glob_\(programming\)) matching. * Supports Globstar. * Supports brace expansion. * Supports negation. * Uses [YAML](https://yaml.org/) syntax for specifying patterns. * Supports [YAML anchors & aliases](https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml#L8-L12). * Supports [YAML multi-line strings](https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml#L13-L16). And many more... ## Usage > \[!IMPORTANT] > > * **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. > * **Mono Repositories**: To avoid pulling the entire branch history, you can utilize the default [`actions/checkout`](https://github.com/actions/checkout#usage)'s [`fetch-depth`](https://github.com/actions/checkout#usage) of `1` for [`pull_request`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) events. > * **Quoting Multiline Inputs**: Avoid using single or double quotes for [multiline](https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml#L13-L16) inputs. The value is already a string separated by a newline character. Refer to the [Examples](#examples-) section for more information. > * **Credentials Persistence**: If [`fetch-depth`](https://github.com/actions/checkout#usage) is not set to 0, make sure to set [`persist-credentials`](https://github.com/actions/checkout#usage) to `true` when configuring [`actions/checkout`](https://github.com/actions/checkout#usage). > * **Matching Files and Folders**: To match all files and folders under a directory, this requires a globstar pattern e.g. `dir_name/**` which matches any number of subdirectories and files. 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. ### On [`pull_request`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) Detect changes to all files in a Pull request relative to the target branch or since the last pushed commit. #### Using local .git directory ``` … ``` #### Using Github's API :octocat: ``` … ``` ### On [`push`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push) ⬆️ Detect changes to files made since the last pushed commit. ``` … ``` ### Other supported events :electron: * [schedule](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule) * [release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release) * [workflow\_dispatch](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch) * [workflow\_run](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run) * [merge\_group](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#merge_group) * [issue\_comment](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issue_comment) * ...and many more To access more examples, navigate to the [Examples](#examples-) section. If you feel generous and want to show some extra appreciation: Support this project with a :star: [![Buy me a coffee][buymeacoffee-shield]][buymeacoffee] [buymeacoffee]: https://www.buymeacoffee.com/jackton1 [buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png > \[!IMPORTANT] > > * When using `files_yaml*` inputs: > * All keys must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. > > For example, `test` or `test_key` or `test-key` or `_test_key` are all valid choices. ## Inputs ⚙️ ``` … ``` ## Useful Acronyms | Acronym | Meaning | |:---------:|:------------:| | A | Added | | C | Copied | | M | Modified | | D | Deleted | | R | Renamed | | T | Type changed | | U | Unmerged | | X | Unknown | > \[!IMPORTANT] > > * When using `files_yaml*` inputs: > * it's required to prefix all outputs with the key to ensure that the correct outputs are accessible. > > For example, if you use `test` as the key, you can access outputs like `added_files`, `any_changed`, and so on by prefixing them with the key `test_added_files` or `test_any_changed` etc. ## Outputs | OUTPUT | TYPE | DESCRIPTION | |------------------------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [added\_files](#output_added_files) | string | Returns only files that are
Added (A). | | [added\_files\_count](#output_added_files_count) | string | Returns the number of `added_files` | | [all\_changed\_and\_modified\_files](#output_all_changed_and_modified_files) | string | Returns all changed and modified
files i.e. a combination of
(ACMRDTUX) | | [all\_changed\_and\_modified\_files\_count](#output_all_changed_and_modified_files_count) | string | Returns the number of `all_changed_and_modified_files` | | [all\_changed\_files](#output_all_changed_files) | string | Returns all changed files i.e.
a combination of all added,
copied, modified and renamed files
(ACMR) | | [all\_changed\_files\_count](#output_all_changed_files_count) | string |