How rules are run

When ick runs a rule, it takes these steps:

  • Files from your local directory are copied to a temporary directory. Only the files mentioned in the input setting will be copied. This is true even for project- and repo-scoped rules, though for those rules input defaults to all files.

  • Your rule doesn’t run in your local directory, and will only have access to files copied because of the input setting. Each rule gets its own temporary directory so they can run independently.

  • The code of the rule is executed as a separate process. Different impl values use different execution engines, but all share common behavior:

    • File-scoped rules get file paths to operate on as multiple command-line arguments. Their actions should be limited to those files. Ick might run multiple processes for one rule, with different subsets of the requested files passed to each process. If you also request extra_inputs those will be present, but you shouldn’t modify them.

    • Ick creates environment variables to provide extra information beyond the copied files:

      • ICK_REPO_PATH is the path to the original working directory. Use this if you need information that isn’t in file content.

      • ICK_REPO_UPSTREAM is the upstream URL of the repository, taken from the upstream remote if present, otherwise origin. This is the raw URL from git config — it may have a trailing slash, and may be an SSH URL (git@github.com:...), a git+https:// URL, or any other form git accepts. Prefer this over reading ICK_REPO_PATH and shelling out to git config yourself, especially if your rule should only run against certain upstream repositories. Not set if no remote is configured.

      • ICK_APPLY exists (with a value of “1”) if the rule is running with the --apply option. Use this if your rule makes changes outside the files in the working tree. Only make those changes if this variable indicates that the rule is being applied.

      • ICK_TEST_NAME is the relative path to the test being run.

    • Rules can make changes to the local copies of files, delete files, or create new files. Any file that might be modified, created, or deleted must be declared in the rule’s outputs setting.

    • Rules can also make changes beyond the local copies of files. They might change settings in an external service, update databases, or anything at all. Rules should only make these changes if ICK_APPLY is set.

  • When the rule has finished running, ick examines two results to determine what happened:

    • The temporary file copies are checked for files that have been modified, added, or deleted.

    • The exit status of the process is checked. 0 indicates success, 99 is a special signal that work needs to be done, and other statuses are failures of the rule.

  • These are possible outcomes:

    • If files have been changed and the code exited successfully (status code 0), then the rule is considered a successful code modification. Ick will use the diffs of the changes in various ways: report on them, display them, copy the changes back to your working directory.

    • If files have been changed but the exit status is 99, then the rule has made a start on a change, but the user needs to finish it somehow.

    • If the rule makes no changes and exits with 0, then nothing needed to be done and nothing was done.