{"id":16475946,"url":"https://github.com/softprops/diffset","last_synced_at":"2025-03-21T07:30:21.925Z","repository":{"id":53766322,"uuid":"233282469","full_name":"softprops/diffset","owner":"softprops","description":"A GitHub Action for producing lists of files that changed between branches","archived":false,"fork":false,"pushed_at":"2025-03-04T15:31:08.000Z","size":1371,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-14T21:09:26.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softprops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"softprops"}},"created_at":"2020-01-11T19:01:36.000Z","updated_at":"2025-03-04T15:31:11.000Z","dependencies_parsed_at":"2024-07-18T00:04:22.770Z","dependency_job_id":"7a59b3c1-c9ed-45d7-96c4-ec6ed79df8b7","html_url":"https://github.com/softprops/diffset","commit_stats":{"total_commits":57,"total_committers":1,"mean_commits":57.0,"dds":0.0,"last_synced_commit":"db8c4e13f5cc3f8ab666ba2cb6998b688058a41c"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fdiffset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fdiffset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fdiffset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Fdiffset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softprops","download_url":"https://codeload.github.com/softprops/diffset/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244757014,"owners_count":20505301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T12:40:56.468Z","updated_at":"2025-03-21T07:30:21.428Z","avatar_url":"https://github.com/softprops.png","language":"TypeScript","funding_links":["https://ko-fi.com/softprops"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  diffset\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n   A GitHub Action for producing lists of files that changed between branches\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/softprops/diffset/actions\"\u003e\n\t\t\u003cimg src=\"https://github.com/softprops/diffset/workflows/Main/badge.svg\"/\u003e\n\t\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## ⚡ why bother\n\nThe goal of a workflow is to do its work as quickly as possible. A core feature of GitHub actions enables this called [path filtering](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths)\n\nMany 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](https://help.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions#about-billing-for-github-actions).\n\n✨ Doing less is faster than doing more ✨\n\n## 🤸 Usage\n\nThe typical setup for diffset involves adding job step using `softprops/diffset@v1`.\n\nThis 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.\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n+     - name: Diffset\n+       id: diffset\n+       uses: softprops/diffset@v2\n      - name: Print Diffset\n        run: ls -al ${{ steps.diffset.outputs.files }}\n```\n\n### 💅 Customizing\n\nThe 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.\n\n#### Custom diff sets\n\nDiffset 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.\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Diffset\n        id: diffset\n        uses: softprops/diffset@v2\n+       with:\n+         special_files: |\n+           src/special/**/*.ts\n+           src/or-these/**/*.ts\n      - name: Print Special Files\n        if: diffset.outputs.special_files\n        run: ls -al ${{ steps.diffset.outputs.special_files }}\n      - name: Other work\n        run: echo \"...\"\n```\n\n#### Custom base branch\n\nMost 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`\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Diffset\n        id: diffset\n        uses: softprops/diffset@v2\n+       with:\n+         base: develop\n      - name: Other work\n        run: ls -al ${{ steps.diffset.outputs.files }}\n```\n\n#### inputs\n\nThe following are optional as `step.with` keys\n\nThis action supports dynamically named inputs which will result in dynamically named outputs.\nSpecifically this action accepts any inputs with a suffix of `_files`\n\n| Name      | Type   | Description                                      |\n| --------- | ------ | ------------------------------------------------ |\n| `*_files` | string | A file pattern to filter changed files           |\n| `base`    | string | Base branch for comparison. Defaults to \"master\" |\n\n#### outputs\n\nThe following outputs can be accessed via `${{ steps.\u003cstep-id\u003e.outputs }}` from this action\n\nThis action supports dynamically named inputs which will result in dynamically named outputs.\nSpecifically this action yields outputs based on inputs named with a suffix of `_files`\n\n| Name      | Type   | Description                                                                |\n| --------- | ------ | -------------------------------------------------------------------------- |\n| `*_files` | string | A space delimited list of files that changed that matched an input pattern |\n\n### 💁‍♀️ pro tips\n\nIn 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.\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Diffset\n        id: diffset\n        uses: softprops/diffset@v2\n       with:\n         special_files: |\n           src/special/**/*.ts\n           src/or-these/**/*.ts\n      - name: Checkout\n+       if: diffset.outputs.special_files\n        uses: actions/checkout@v4\n```\n\nDoug Tangren (softprops) 2019-2021\n\n.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fdiffset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftprops%2Fdiffset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Fdiffset/lists"}