changed-files

Note

• This action solely identifies files that have changed for events such aspull_request*,push,merge_group,release, and many more. 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 🚀

Usage 💻

Important

• Push Events: When configuringactions/checkout, make sure to setfetch-depth to either0 or2, depending on your use case.
• Mono Repositories: To avoid pulling the entire branch history, you can utilize the defaultactions/checkout'sfetch-depth of1 forpull_request events.
• Quoting Multiline Inputs: Avoid using single or double quotes formultiline inputs. The value is already a string separated by a newline character. Refer to theExamples section for more information.
• Credentials Persistence: Iffetch-depth is not set to 0, make sure to setpersist-credentials totrue when configuringactions/checkout.
• 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.

Onpull_request 🔀

Using local .git directory 📁

name:CIon:pull_request:branches:      -mainjobs:# ------------------------------------------------------------------------------------------------------------------------------------------------# Event `pull_request`: Compare the last commit of the main branch or last remote commit of the PR branch -> to the current commit of a PR branch.# ------------------------------------------------------------------------------------------------------------------------------------------------changed_files:runs-on:ubuntu-latest# windows-latest || macos-latestname:Test changed-filessteps:      -uses:actions/checkout@v4# -----------------------------------------------------------------------------------------------------------# Example 1# -----------------------------------------------------------------------------------------------------------      -name:Get changed filesid:changed-filesuses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46# To compare changes between the current commit and the last pushed remote commit set `since_last_remote_commit: true`. e.g# with:#   since_last_remote_commit: true      -name:List all changed filesenv:ALL_CHANGED_FILES:${{ steps.changed-files.outputs.all_changed_files }}run:|          for file in ${ALL_CHANGED_FILES}; do            echo "$file was changed"          done# -----------------------------------------------------------------------------------------------------------# Example 2# -----------------------------------------------------------------------------------------------------------      -name:Get all changed markdown filesid:changed-markdown-filesuses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46with:# Avoid using single or double quotes for multiline patternsfiles:|            **.md            docs/**.md      -name:List all changed files markdown filesif:steps.changed-markdown-files.outputs.any_changed == 'true'env:ALL_CHANGED_FILES:${{ steps.changed-markdown-files.outputs.all_changed_files }}run:|          for file in ${ALL_CHANGED_FILES}; do            echo "$file was changed"          done# -----------------------------------------------------------------------------------------------------------# Example 3# -----------------------------------------------------------------------------------------------------------      -name:Get all test, doc and src files that have changedid:changed-files-yamluses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46with:files_yaml:|            doc:              - '**.md'              - docs/**            test:              - test/**              - '!test/**.md'            src:              - src/**# Optionally set `files_yaml_from_source_file` to read the YAML from a file. e.g `files_yaml_from_source_file: .github/changed-files.yml`      -name:Run step if test file(s) change# 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.if:steps.changed-files-yaml.outputs.test_any_changed == 'true'env:TEST_ALL_CHANGED_FILES:${{ steps.changed-files-yaml.outputs.test_all_changed_files }}run:|          echo "One or more test file(s) has changed."          echo "List all the files that have changed: $TEST_ALL_CHANGED_FILES"            -name:Run step if doc file(s) changeif:steps.changed-files-yaml.outputs.doc_any_changed == 'true'env:DOC_ALL_CHANGED_FILES:${{ steps.changed-files-yaml.outputs.doc_all_changed_files }}run:|          echo "One or more doc file(s) has changed."          echo "List all the files that have changed: $DOC_ALL_CHANGED_FILES"# -----------------------------------------------------------------------------------------------------------# Example 4# -----------------------------------------------------------------------------------------------------------      -name:Get changed files in the docs folderid:changed-files-specificuses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46with:files:docs/*.{js,html}# Alternatively using: `docs/**`files_ignore:docs/static.js      -name:Run step if any file(s) in the docs folder changeif:steps.changed-files-specific.outputs.any_changed == 'true'env:ALL_CHANGED_FILES:${{ steps.changed-files-specific.outputs.all_changed_files }}run:|          echo "One or more files in the docs folder has changed."          echo "List all the files that have changed: $ALL_CHANGED_FILES"

Using Github's API

name:CIon:pull_request:branches:      -mainjobs:# -------------------------------------------------------------# Event `pull_request`: Returns all changed pull request files.# --------------------------------------------------------------changed_files:# NOTE:# - This is limited to pull_request* events and would raise an error for other events.# - A maximum of 3000 files can be returned.# - For more flexibility and no limitations see "Using local .git directory" above.runs-on:ubuntu-latest# windows-latest || macos-latestname:Test changed-filespermissions:pull-requests:readsteps:      -name:Get changed filesid:changed-filesuses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46      -name:List all changed filesenv:ALL_CHANGED_FILES:${{ steps.changed-files.outputs.all_changed_files }}run:|          for file in ${ALL_CHANGED_FILES}; do            echo "$file was changed"          done

Onpush ⬆️

name:CIon:push:branches:      -mainjobs:# -------------------------------------------------------------# Using GitHub's API is not supported for push events# -------------------------------------------------------------## ----------------------------------------------------------------------------------------------# Using local .git history# ----------------------------------------------------------------------------------------------# Event `push`: Compare the preceding remote commit -> to the current commit of the main branch# ----------------------------------------------------------------------------------------------changed_files:runs-on:ubuntu-latest# windows-latest || macos-latestname:Test changed-filessteps:      -uses:actions/checkout@v4with:fetch-depth:0# OR "2" -> To retrieve the preceding commit.      -name:Get changed filesid:changed-filesuses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46# NOTE: `since_last_remote_commit: true` is implied by default and falls back to the previous local commit.      -name:List all changed filesenv:ALL_CHANGED_FILES:${{ steps.changed-files.outputs.all_changed_files }}run:|          for file in ${ALL_CHANGED_FILES}; do            echo "$file was changed"          done...

Other supported events

Important

• When usingfiles_yaml* inputs:

  • All keys must start with a letter or_ and contain only alphanumeric characters,-, or_.

    For example,test ortest_key ortest-key or_test_key are all valid choices.

Inputs ⚙️

-uses:tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0# v46id:changed-fileswith:# Github API URL.# Type: string# Default: "${{ github.api_url }}"api_url:''# Specify a different base commit# SHA or branch used for# comparing changes# Type: stringbase_sha:''# Exclude changes outside the current# directory and show path names# relative to it. NOTE: This# requires you to specify the# top-level directory via the `path`# input.# Type: boolean# Default: "true"diff_relative:''# Output unique changed directories instead# of filenames. NOTE: This returns# `.` for changed files located# in the current working directory# which defaults to `$GITHUB_WORKSPACE`.# Type: boolean# Default: "false"dir_names:''# Include only directories that have# been deleted as opposed to# directory names of files that# have been deleted in the# `deleted_files` output when `dir_names` is# set to `true`.# Type: boolean# Default: "false"dir_names_deleted_files_include_only_deleted_dirs:''# Exclude the current directory represented# by `.` from the output# when `dir_names` is set to# `true`.# Type: boolean# Default: "false"dir_names_exclude_current_dir:''# File and directory patterns to# include in the output when# `dir_names` is set to `true`.# NOTE: This returns only the# matching files and also the# directory names.# Type: stringdir_names_include_files:''# Separator used to split the# `dir_names_include_files` input# Type: string# Default: "\n"dir_names_include_files_separator:''# Limit the directory output to# a maximum depth e.g `test/test1/test2`# with max depth of `2`# returns `test/test1`.# Type: stringdir_names_max_depth:''# Escape JSON output.# Type: boolean# Default: "true"escape_json:''# Exclude changes to submodules.# Type: boolean# Default: "false"exclude_submodules:''# Fail when the initial diff# fails.# Type: boolean# Default: "false"fail_on_initial_diff_error:''# Fail when the submodule diff# fails.# Type: boolean# Default: "false"fail_on_submodule_diff_error:''# Fetch additional history for submodules.# Type: boolean# Default: "false"fetch_additional_submodule_history:''# Depth of additional branch history# fetched. NOTE: This can be# adjusted to resolve errors with# insufficient history.# Type: string# Default: "25"fetch_depth:''# Maximum number of retries to# fetch missing history.# Type: string# Default: "20"fetch_missing_history_max_retries:''# File and directory patterns used# to detect changes (Defaults to the entire repo if unset). NOTE:# Multiline file/directory patterns should not# include quotes.# Type: stringfiles:''# Source file(s) used to populate# the `files` input.# Type: stringfiles_from_source_file:''# Separator used to split the# `files_from_source_file` input.# Type: string# Default: "\n"files_from_source_file_separator:''# Ignore changes to these file(s).# NOTE: Multiline file/directory patterns should# not include quotes.# Type: stringfiles_ignore:''# Source file(s) used to populate# the `files_ignore` input# Type: stringfiles_ignore_from_source_file:''# Separator used to split the# `files_ignore_from_source_file` input# Type: string# Default: "\n"files_ignore_from_source_file_separator:''# Separator used to split the# `files_ignore` input# Type: string# Default: "\n"files_ignore_separator:''# YAML used to define a# set of file patterns to# ignore changes# Type: stringfiles_ignore_yaml:''# Source file(s) used to populate# the `files_ignore_yaml` input. Example: https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml# Type: stringfiles_ignore_yaml_from_source_file:''# Separator used to split the# `files_ignore_yaml_from_source_file` input# Type: string# Default: "\n"files_ignore_yaml_from_source_file_separator:''# Separator used to split the# `files` input# Type: string# Default: "\n"files_separator:''# YAML used to define a# set of file patterns to# detect changes# Type: stringfiles_yaml:''# Source file(s) used to populate# the `files_yaml` input. Example: https://github.com/tj-actions/changed-files/blob/main/test/changed-files.yml# Type: stringfiles_yaml_from_source_file:''# Separator used to split the# `files_yaml_from_source_file` input# Type: string# Default: "\n"files_yaml_from_source_file_separator:''# Include `all_old_new_renamed_files` output. Note this# can generate a large output# See: #501.# Type: boolean# Default: "false"include_all_old_new_renamed_files:''# Output list of changed files# in a JSON formatted string# which can be used for# matrix jobs. Example: https://github.com/tj-actions/changed-files/blob/main/.github/workflows/matrix-example.yml# Type: boolean# Default: "false"json:''# Output changed files in a# format that can be used# for matrix jobs. Alias for# setting inputs `json` to `true`# and `escape_json` to `false`.# Type: boolean# Default: "false"matrix:''# Apply the negation patterns first.# NOTE: This affects how changed# files are matched.# Type: boolean# Default: "false"negation_patterns_first:''# Split character for old and# new renamed filename pairs.# Type: string# Default: " "old_new_files_separator:''# Split character for old and# new filename pairs.# Type: string# Default: ","old_new_separator:''# Directory to store output files.# Type: string# Default: ".github/outputs"output_dir:''# Output renamed files as deleted# and added files.# Type: boolean# Default: "false"output_renamed_files_as_deleted_and_added:''# Specify a relative path under# `$GITHUB_WORKSPACE` to locate the repository.# Type: string# Default: "."path:''# Use non-ASCII characters to match# files and output the filenames# completely verbatim by setting this# to `false`# Type: boolean# Default: "true"quotepath:''# Recover deleted files.# Type: boolean# Default: "false"recover_deleted_files:''# Recover deleted files to a# new destination directory, defaults to# the original location.# Type: stringrecover_deleted_files_to_destination:''# File and directory patterns used# to recover deleted files, defaults# to the patterns provided via# the `files`, `files_from_source_file`, `files_ignore` and# `files_ignore_from_source_file` inputs or all deleted# files if no patterns are# provided.# Type: stringrecover_files:''# File and directory patterns to# ignore when recovering deleted files.# Type: stringrecover_files_ignore:''# Separator used to split the# `recover_files_ignore` input# Type: string# Default: "\n"recover_files_ignore_separator:''# Separator used to split the# `recover_files` input# Type: string# Default: "\n"recover_files_separator:''# Apply sanitization to output filenames# before being set as output.# Type: boolean# Default: "true"safe_output:''# Split character for output strings.# Type: string# Default: " "separator:''# Specify a different commit SHA# or branch used for comparing# changes# Type: stringsha:''# Get changed files for commits# whose timestamp is older than# the given time.# Type: stringsince:''# Use the last commit on# the remote branch as the# `base_sha`. Defaults to the last# non-merge commit on the target# branch for pull request events# and the previous remote commit# of the current branch for# push events.# Type: boolean# Default: "false"since_last_remote_commit:''# Skip initially fetching additional history# to improve performance for shallow# repositories. NOTE: This could lead# to errors with missing history.# It's intended to be used# when you've fetched all necessary# history to perform the diff.# Type: boolean# Default: "false"skip_initial_fetch:''# Tags pattern to ignore.# Type: stringtags_ignore_pattern:''# Tags pattern to include.# Type: string# Default: "*"tags_pattern:''# GitHub token used to fetch# changed files from Github's API.# Type: string# Default: "${{ github.token }}"token:''# Get changed files for commits# whose timestamp is earlier than# the given time.# Type: stringuntil:''# Use POSIX path separator `/`# for output file paths on# Windows.# Type: boolean# Default: "false"use_posix_path_separator:''# Force the use of Github's# REST API even when a# local copy of the repository# exists# Type: boolean# Default: "false"use_rest_api:''# Write outputs to the `output_dir`# defaults to `.github/outputs` folder. NOTE:# This creates a `.txt` file# by default and a `.json`# file if `json` is set# to `true`.# Type: boolean# Default: "false"write_output_files:''

Useful Acronyms 🧮

Important

• When usingfiles_yaml* inputs:

  • it's required to prefix all outputs with the key to ensure that the correct outputs are accessible.

    For example, if you usetest as the key, you can access outputs likeadded_files,any_changed, and so on by prefixing them with the keytest_added_files ortest_any_changed etc.

Outputs 📤

Versioning 🏷️

Examples 📄

Real-world usage 🌐

Open source projects 📦

Scalability Example 📈

Important Notice⚠️

Important

• Spaces in file names can introduce bugs when using bash loops. See:#216However, this action will handle spaces in file names, with a recommendation of using a separator to prevent any hidden issues.

  

Migration guide 🔄

...      - name: Get specific changed files        id: changed-files-specific        uses: tj-actions/changed-files@v24        with:          files: |-            \.sh$-            .(sql|py)$-            ^(dir1|dir2)+            **/*.{sh,sql,py}+            {dir1,dir2}/**

Credits 👏

Report Bugs 🐛

Contributors ✨