A GitHub Action for producing lists of files that changed between branches
The goal of a workflow is to do its work as quickly as possible. A core feature of GitHub actions enables this called path filtering
Many command line tools accept a list of files as inputs to limit the amount of work they need to do. Diffset is a tool that targets the usecase of maximally efficient workflows where such tools are in use so that you can apply them to only the things that changed. Save yourself some time and money.
✨ Doing less is faster than doing more ✨
The typical setup for diffset involves adding job step using softprops/diffset@v1.
This will collect a list of files that have changed and export them to an output named files. It retrieves this list of files from the GitHub api and as such it will need your repositories GITHUB_TOKEN secret.
name: Main
on: push
jobs:
main:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
+ - name: Diffset
+ id: diffset
+ uses: softprops/diffset@v2
- name: Print Diffset
run: ls -al ${{ steps.diffset.outputs.files }}The default behavior of diff is to simply introduce an output named files which is the set of changed files in your branch. In other cases certain workflows may benefit from skipping jobs when a class of files are not changed.
Diffset also allows you to create filters for named sets of files to avoid doing unessessary work within your pipeline and produces an named output for those sets of files when they changed. These named sets of files can include multiple patterns for any given set to allow for maximum flexibility.
name: Main
on: push
jobs:
main:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Diffset
id: diffset
uses: softprops/diffset@v2
+ with:
+ special_files: |
+ src/special/**/*.ts
+ src/or-these/**/*.ts
- name: Print Special Files
if: diffset.outputs.special_files
run: ls -al ${{ steps.diffset.outputs.special_files }}
- name: Other work
run: echo "..."Most GitHub repositories use a default "master" branch. Diffset uses this as a basis of comparison by default. If you use a different base branch you can use the steps.with key to provide a custom base
name: Main
on: push
jobs:
main:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Diffset
id: diffset
uses: softprops/diffset@v2
+ with:
+ base: develop
- name: Other work
run: ls -al ${{ steps.diffset.outputs.files }}The following are optional as step.with keys
This action supports dynamically named inputs which will result in dynamically named outputs.
Specifically this action accepts any inputs with a suffix of _files
| Name | Type | Description |
|---|---|---|
*_files |
string | A file pattern to filter changed files |
base |
string | Base branch for comparison. Defaults to "master" |
The following outputs can be accessed via ${{ steps.<step-id>.outputs }} from this action
This action supports dynamically named inputs which will result in dynamically named outputs.
Specifically this action yields outputs based on inputs named with a suffix of _files
| Name | Type | Description |
|---|---|---|
*_files |
string | A space delimited list of files that changed that matched an input pattern |
In more complicated workflows you may find that simply cloning your repository takes a succfiently long about of time. In these cases you can opt to generate a diffset first, then checkout only if needed.
name: Main
on: push
jobs:
main:
runs-on: ubuntu-latest
steps:
- name: Diffset
id: diffset
uses: softprops/diffset@v2
with:
special_files: |
src/special/**/*.ts
src/or-these/**/*.ts
- name: Checkout
+ if: diffset.outputs.special_files
uses: actions/checkout@v4Doug Tangren (softprops) 2019-2021
.