Introduction to the changed-files Project
The changed-files project is a powerful tool designed to effortlessly track and manage changed files and directories within a GitHub repository. It is particularly beneficial for developers and teams working on complex projects where monitoring code changes is critical for maintaining code quality and ensuring smooth collaboration.
Overview
The changed-files project is implemented as a GitHub Action that helps to identify files that have changed across various events, such as pull requests, pushes, and releases. This action returns the relative paths of changed files or directories from the project root, making it easier for developers to focus on exactly what has changed.
Key Features
- Fast Execution: The action executes quickly, usually within 0-10 seconds.
- Versatile Detection: It uses either GitHub's REST API or Git’s native diff command to determine changed files.
- Debugging Support: Provides facilities that ease the debugging process.
- Scalability: Efficiently handles large and mono repositories, and supports Git submodules.
- Merge Queues: Supports merge queues for pull requests, common in larger project settings.
- JSON Output: Generates escaped JSON outputs for matrix jobs, helpful for complex workflows.
- Directory Listings: Lists changed directories with options to limit depth or exclude the current directory.
- Outputs: Writes outputs to a
.txtor.jsonfile for further processing needs. - File Restoration: Can restore deleted files to a former or new location.
- Optimized Commit Fetching: Supports fetching a fixed number of commits to boost performance.
- Cross-Platform Compatibility: Works seamlessly on Linux, MacOS, and Windows platforms.
- Support for Self-Hosted Runners: Compatible with GitHub-hosted and self-hosted runners, as well as GitHub Enterprise Server.
Usage Examples
On Pull Requests
Developers can use this action in workflows triggered by pull requests to detect and list all files and directories that have changed relative to the target branch since the last commit. This can be done using either the local .git directory or GitHub's API, making it flexible for different use cases.
On Push Events
For push events, the action compares the previous remote commit with the current commit, making it suitable for continuous integration setups.
Other Supported Events
The action also supports other GitHub events like schedule, release, workflow_dispatch, workflow_run, and merge_group, providing versatility in various stages of the software development lifecycle.
Inputs and Outputs
The action offers a rich set of inputs allowing users to configure it according to their needs, including options to specify base commit references, ignore submodules, set fetch depths, and define file patterns. The outputs include lists of all changed files or directories, which can be used in subsequent steps of the CI/CD pipeline.
Important Considerations
- Ensure proper configuration of fetch depth for optimized execution.
- Use glob patterns accurately for file inclusion/exclusion.
- For security, manage credentials appropriately when dealing with private repositories.
Conclusion
Overall, the changed-files project is a highly adaptive tool that helps developers automate the tracking of file changes during code reviews and integrations. By integrating this action into GitHub workflows, teams can leverage its capabilities to maintain a high quality of code and streamline their development processes.