affected

A tool to find affected files or projects in a git repository and run commands on them.

Features

• determine affected files or projects for a git repository
• view affected files or projects
• run commands on affected files or projects
• redirects variables from .env files to the commands

Installation

From Crates.io

This is the recommended way to install the tool.

cargo install affected

From pre-built binaries

Download the latest release from the releases page

Supported platforms:

• Linux (x86_64)
• Linux (aarch64)
• macOS (x86_64)

Setup

The init command initializes the repository for use with the affected tool.

cd /path/to/repo

# with the default base branch
affected init

# or with a different base branch
affected --base=develop init

This command creates a .affected.yml file in the root of the repository.

Configuration

# .affected.yml
base: main

Usage

The format of the command is:

Usage: affected [OPTIONS] <COMMAND>

Commands:
  init  Initialize the configuration file
  view  View affected files or projects
  help  Print this message or the help of the given subcommand(s)

Options:
      --repo <REPO>  Optional repo path, defaults to current directory
      --base <BASE>  Base of the current branch (usually main). Falls back to 'main' or 'master' if not provided
  -h, --help         Print help

Example

For the feature branch checked out, and the main branch is develop:

# List all affected files in the current repository
affected --base=develop view files

# List all affected projects in a different repository
affected --repo=/path/to/repo --base=develop view projects

Tasks

Tasks can be defined in the .affected.yml file to run commands on affected files.

base: develop

tasks:
  - name: lint
    description: Runs eslint for all affected files
    patterns: [ '*.ts', '*.tsx', '*.js', '*.jsx' ]
    separator: ' ' # Optional separator for the files list
    commands: [ 'echo {files}' ]

    # Running eslint for affected files
    # commands: [ 'npx eslint {files}' ]

The name field is the name of the task.
The patterns field is an array of file patterns to match.
The separator field is an optional separator for the files list.
The commands field is an array of commands to run on the affected files.
The {files} placeholder is replaced with the list of affected files.

Alternative formatting:

base: main
tasks:
  - name: lint
    description: Runs eslint for all affected files
    patterns:
      - '*.ts'
      - '*.tsx'
      - '*.js'
      - '*.jsx'
    commands:
      - echo {files}
      - npx eslint {files}

Example:

affected run lint

File Separators

The separator for the list of files can be set using the separators task field. This is useful when the command requires a different separator than the default.

For example, the karma task requires a comma-separated list of files.

tasks:
  - name: karma
    description: Runs karma for all affected files
    patterns: [ '*.ts' ]
    separator: ',' # Comma-separated list
    commands: [ 'karma start --include {files}' ] 

The default separator is a space.

Environment Variables

Environment variables can be set in the .env file in the root of the repository.

# .env
NODE_ENV=development
E2E_HOST="http://localhost"
E2E_PORT=4200

The variables are passed to the commands.

tasks:
  - name: demo
    description: Passes environment variables to the command
    patterns: [ '*.ts', '*.tsx', '*.js', '*.jsx' ]
    commands: [ 'echo ${E2E_HOST}:${E2E_PORT}' ]

Modify some source files and run the task:

affected run demo

The output is http://localhost:4200.

Developing

Log Levels

The log level can be set using the LOG_LEVEL environment variable.

export LOG_LEVEL=DEBUG
affected [OPTIONS] <COMMAND>

The following log levels are available:

• TRACE
• DEBUG
• INFO
• WARN
• ERROR

The default log level is INFO.

Local Runs

You can compile and run the application locally for testing.

cargo build
sudo ln -s $(pwd)/target/debug/affected /usr/local/bin/affected

# Run the application
cd /path/to/repo
affected view files

# Full debug output
LOG_LEVEL=DEBUG affected run lint