{"id":13563290,"url":"https://github.com/fugue/zim","last_synced_at":"2025-12-25T14:26:22.375Z","repository":{"id":38474899,"uuid":"248220278","full_name":"fugue/zim","owner":"fugue","description":"A caching build system for teams using monorepos","archived":false,"fork":false,"pushed_at":"2023-02-25T08:09:51.000Z","size":370,"stargazers_count":87,"open_issues_count":8,"forks_count":5,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-03T19:40:08.828Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fugue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2020-03-18T12:03:34.000Z","updated_at":"2024-12-11T13:20:47.000Z","dependencies_parsed_at":"2024-06-19T00:04:55.751Z","dependency_job_id":"3ac7bd98-f424-42fb-861e-4610ff5b2468","html_url":"https://github.com/fugue/zim","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/fugue/zim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fzim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fzim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fzim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fzim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fugue","download_url":"https://codeload.github.com/fugue/zim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fzim/sbom","scorecard":{"id":413236,"data":{"date":"2025-08-11","repo":{"name":"github.com/fugue/zim","commit":"6cd6d3491efcc3c12446b05d292d20451518542f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.5,"checks":[{"name":"Code-Review","score":6,"reason":"Found 19/30 approved changesets -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v0.6.0 not signed: https://api.github.com/repos/fugue/zim/releases/70397995","Warn: release artifact v0.5.0 not signed: https://api.github.com/repos/fugue/zim/releases/51554485","Warn: release artifact v0.4.0 not signed: https://api.github.com/repos/fugue/zim/releases/37867656","Warn: release artifact v0.3.0 not signed: https://api.github.com/repos/fugue/zim/releases/33721188","Warn: release artifact v0.2.0 not signed: https://api.github.com/repos/fugue/zim/releases/28567957","Warn: release artifact v0.6.0 does not have provenance: https://api.github.com/repos/fugue/zim/releases/70397995","Warn: release artifact v0.5.0 does not have provenance: https://api.github.com/repos/fugue/zim/releases/51554485","Warn: release artifact v0.4.0 does not have provenance: https://api.github.com/repos/fugue/zim/releases/37867656","Warn: release artifact v0.3.0 does not have provenance: https://api.github.com/repos/fugue/zim/releases/33721188","Warn: release artifact v0.2.0 does not have provenance: https://api.github.com/repos/fugue/zim/releases/28567957"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":0,"reason":"22 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2022-0391 / GHSA-6jvc-q2x7-pchv / GHSA-76wf-9vgp-pj7w","Warn: Project is vulnerable to: GO-2022-0635 / GHSA-7f33-f4f5-xwgw","Warn: Project is vulnerable to: GO-2022-0646 / GHSA-f5pg-7wfw-84q9","Warn: Project is vulnerable to: GO-2021-0061 / GHSA-r88r-gmrh-7j83","Warn: Project is vulnerable to: GO-2020-0036 / GHSA-wxc4-f4m6-wwqv","Warn: Project is vulnerable to: GO-2024-2947 / GHSA-v6v8-xj6m-xwqh","Warn: Project is vulnerable to: GO-2022-0236 / GHSA-h86h-8ppg-mxmh","Warn: Project is vulnerable to: GO-2021-0238 / GHSA-83g2-8m93-v3w7","Warn: Project is vulnerable to: GO-2022-0288","Warn: Project is vulnerable to: GO-2022-0969 / GHSA-69cg-p879-7622","Warn: Project is vulnerable to: GO-2022-1144 / GHSA-xrjj-mj9h-534m","Warn: Project is vulnerable to: GO-2023-1571 / GHSA-vvpx-j8f3-3w6h","Warn: Project is vulnerable to: GO-2023-1988 / GHSA-2wrh-6pvc-2jm9","Warn: Project is vulnerable to: GO-2023-2102 / GHSA-4374-p667-p6c8","Warn: Project is vulnerable to: GHSA-qppj-fm5r-hxr3","Warn: Project is vulnerable to: GO-2024-2687 / GHSA-4v7x-pqxf-cx7m","Warn: Project is vulnerable to: GO-2024-3333","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw","Warn: Project is vulnerable to: GO-2022-0493 / GHSA-p782-xgp4-8hr8","Warn: Project is vulnerable to: GO-2021-0113 / GHSA-ppp9-7jff-5vj2","Warn: Project is vulnerable to: GO-2022-1059 / GHSA-69ch-w2m2-3vjp"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 27 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T23:13:00.700Z","repository_id":38474899,"created_at":"2025-08-18T23:13:00.700Z","updated_at":"2025-08-18T23:13:00.700Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28031122,"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","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-08-01T13:01:17.405Z","updated_at":"2025-12-25T14:26:22.355Z","avatar_url":"https://github.com/fugue.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Zim\n\n[![CircleCI](https://circleci.com/gh/fugue/zim.svg?style=svg)](https://circleci.com/gh/fugue/zim)\n\nZim is a caching build system that is ideal for teams using monorepos containing\nmany components and dependencies. Its primary goal is fast incremental builds\nacross a team by leveraging a shared cache of rule outputs. It is entirely\nlanguage agnostic and has built-in support for cross-platform builds via Docker.\n\nComponents and rules are defined in a YAML definitions that are conceptually\nsimilar to Makefiles. Each components may inherit from a base template, which\nyields a simple mechanism to build many components in a consistent and\nconfigurable manner.\n\n## Why Zim?\n\nZim offers these advantages to teams developing in a monorepo:\n\n * Fast, parallel builds. Rules run only if inputs have changed and\n   outputs are pulled from a shared cache if someone else built it already.\n\n * Trivially define how to build new component types. Define build steps\n   for components in a few lines of YAML.\n\n * Gain the benefits of isolated build environments and cross-platform\n   compilation via the built-in Docker support. Just specify the Docker\n   image to be used when building a component.\n\n * Flexible input and output resource types. Currently Zim is able to work with\n   both files and Docker images as natively supported resources.\n\n * Easy setup for a shared cache in S3 via an AWS CloudFormation stack.\n\n * Lightweight \u0026 easy to install. Zim is written in Go which means it\n   consists of a single binary when built.\n\n## Inspiration\n\nThis project draws inspiration from the core concepts of GNU Make along with the\ncaching strategy from [Buck](https://buck.build/),\n[Bazel](https://bazel.build/), and [Please](https://please.build/index.html).\n\nLike Make, Zim has a lightweight way to express new rules that define inputs,\noutputs, and the commands needed to create the outputs.\n\nLike Buck, Zim computes _Rule Keys_ which are used to determine whether the\noutput of a rule is already available in the cache, based on the combined\nhashes of all the rule's inputs and configuration.\n\n## Concepts\n\nThe following concepts are key to how Zim operates, although you can just skip\nahead to the *Getting Started* section below if you want to skate by for now.\n\n * **Project** - typically a Git repository that contains the source for\n   multiple services.\n\n * **Component** - a directory in the monorepo which typically relates to a\n   single library, binary, or microservice. In Zim, a Component is described\n   by a `component.yaml` definition.\n\n * **Rule** - a definition that describes an action or build step. Each rule\n   has optional input and output resources, dependencies, and associated\n   commands.\n\n * **Key** - a key is computed for each rule which is unique to the current\n   state of its inputs, dependencies, and rule configuration. This key is\n   used when storing and retrieving output artifacts from the shared cache.\n\n * **Resource** - inputs and outputs from rules, which may be files or other\n   types. Currently only files and Docker images are the two supported types.\n\n * **Provider** - new resource types may be added via providers. This consists\n   of implementing a Go interface and recompiling Zim. Longer term, this could\n   be changed to use IPC or another mechanism to make it easier to extend.\n\n * **Graph** - internally, Zim builds a directed acyclic graph (DAG) containing\n   the rules the user asks to run, along with their transitive dependencies.\n   This graph is created and processed by the scheduler in order to execute\n   rules in order of their dependencies.\n\n * **Scheduler** - the scheduler is responsible for executing rules according\n   to the DAG. The implementation uses Goroutines to parallelize execution of\n   rules that are ready to run.\n\n * **Middleware** - rule execution is decorated and customized by middleware\n   in Zim, similar to how middleware is used to customize HTTP handlers.\n   Logging, caching, and uploads of artifacts are all accomplished via\n   middleware.\n\n## Getting Started\n\nInstall the Zim CLI by cloning this repo and running `go install` at the top level.\nRun `zim -h` to see help regarding available commands and flags. Zim recognizes\nwhen it is run within a Git repository and will automatically discover\n`component.yaml` files within, which define components and their rules.\n\nFor each item in the repository that you would like to build with Zim, add\na `component.yaml` file in the corresponding directory. A simple example to\nbuild a Go program is as follows.\n\n```yaml\nname: myservice\nrules:\n  build:\n    inputs:\n    - \"*.go\"\n    outputs:\n    - ${NAME}\n    command: go build -o ${OUTPUT}\n```\n\nWith that definition saved, you can now enter `zim run build` to get it done.\n\n```shell\n$ zim run build --cache disabled\nrule: myservice.build\ncmd: go build -o ${OUTPUT}\nrule: myservice.build in 1.347 sec [OK]\n```\n\nThe outputs - an executable named `myservice` in this case - are stored in an\n`artifacts` directory located at the root level of the repository.\n\n## Creating the Shared Cache\n\nCurrently Zim supports using AWS infrastructure for its cache backend.\nA CloudFormation stack containing an S3 bucket and a handful of other serverless\ninfrastructure is easily provisioned by using\n[SAM](https://github.com/awslabs/aws-sam-cli).\n\nPrerequisites:\n\n * Install the AWS and SAM CLIs: `pip install awscli aws-sam-cli`\n * [Download Go](https://golang.org/dl/) to build the Zim Lambdas\n\nThe following was tested with the following version of the SAM CLI:\n\n```shell\n$ sam --version\nSAM CLI, version 0.45.0\n```\n\nWith those dependencies installed, run the following to provision cache\ninfrastructure in AWS using a workflow guided by SAM:\n\n```shell\n$ make deploy\n```\n\nWhen the command completes, the URL of your Zim API is printed. This URL should\nbe saved to `~/.zim.yaml` as described in the following section.\n\n## Developer Setup\n\nEach developer should create the file `~/.zim.yaml` on their development\nmachine with two main variables:\n\n  * The team API URL from `make deploy`\n  * Your personal authentication token\n\nWith AWS credentials active for the account containing Zim, run the following\ncommand to create an authentication token for each team member:\n\n```shell\n$ zim add token --email \"joe@example.com\" --name \"Joe\"\n```\n\nEach team member should now add the following to their `~/.zim.yaml`:\n\n```yaml\nurl: \"TEAM_API_URL\"\ntoken: \"MY_TOKEN\"\n```\n\nAlternatively, you can use the environment variables `ZIM_URL` and `ZIM_TOKEN`.\n\n## Cache Mode\n\nYou may override the Zim CLI cache mode. The following modes are available:\n\n * `read-write` - this is the default\n * `write-only` - write to the cache but don't read from it\n * `disabled` - operate in offline mode\n\nTo use this feature, set `cache` in `~/.zim.yaml` as follows:\n\n```yaml\ncache: disabled\n```\n\nOr use the command line flag:\n\n```shell\n$ zim run build --cache disabled\n```\n\n## Running Rules in Docker\n\nTo automatically run rules inside a Docker container, instead of on the host\ndirectly, define a Docker image for each component and set the Docker option.\n\nFor example, to build a Go service in a container, you could use the following:\n\n```yaml\nname: myservice\ndocker:\n  image: circleci/golang:1.12.4\ntoolchain:\n  items:\n  - name: go\n    command: go version\nrules:\n  build:\n    inputs:\n    - \"*.go\"\n    outputs:\n    - ${NAME}\n    command: go build -o ${OUTPUT}\n```\n\nWhen a Docker image is specified for the component, Zim mounts the repository as\na volume and sets the component directory as the working directory when\nexecuting its rules.\n\nNote the use of `toolchain` in the `component.yaml`. The above example includes\nthe output of `go version` in the *Rule Key* so that builds on different\narchitecture receive unique keys in the cache.\n\nTo opt-out of using Docker for certain rules, set the `native` flag as follows:\n\n```yaml\nrules:\n  show-host-arch:\n    native: true\n    command: uname -a\n```\n\n## Docker Platforms\n\nYou may target different architectures using Docker's [multi-CPU architecture support](https://docs.docker.com/desktop/multi-arch). To set the Docker target platform, set `platform` in `~/.zim.yaml` as follows:\n\n```yaml\nplatform: linux/amd64\n```\n\nOr use the command line flag:\n\n```shell\n$ zim run build --platform linux/amd64\n```\n\nYou can list available platforms in Docker by running:\n\n```shell\n$ docker buildx ls\n```\n\n## Rule Keys\n\nThese keys are the basis for Zim caching. Zim uses SHA1 hashes to represent each\nkey. Specifically, the hash is computed on a JSON document containing the\nfollowing information for each rule:\n\n* Project name\n* Component name\n* Rule name\n* Docker image\n* Output artifact count\n* Input file relative paths and their SHA1 hashes\n* Rule dependencies and their keys\n* Environment variables set on the Component and Rule\n* Toolchain\n* Cache key version\n* Rule commands\n* Whether the rule is native\n\nThis information uniquely identifies all the inputs and configuration used\nby a rule. This means, prior to executing a rule, Zim can determine the current\nrule key and check whether an output is stored with the that key in the cache.\nIf so, Zim downloads the output from the cache rather than executing the rule.\n\nZim assumes the rule commands are, in effect, a pure function. In practice\nthis isn't always the case, but is close enough. For example, when Python files\nare compiled to `.pyc` a build timestamp is included, so the build will never\nbe exactly the same, even with the same file inputs.\n\nIf you would like to see a key for a given rule for debugging purposes, you\ncan use the following command:\n\n```shell\n$ zim key -r myservice.build\n```\n\nTo retrieve the underlying information:\n\n```shell\n$ zim key -r myservice.build --detail\n```\n\n## Rule Dependencies\n\nZim supports dependencies between rules, both within a Component and across\nComponents. Collectively, rule dependencies form a directed acyclic graph that\nZim traverses when running rules.\n\nTo define a dependency, use the following syntax in a Component definition:\n\n```yaml\nname: myservice\nkind: go\nrules:\n  build:\n    requires:\n    - component: my_library_a\n      rule: build\n    - component: my_library_b\n      rule: build\n    inputs:\n    - \"*.go\"\n    outputs:\n    - ${NAME}\n    command: go build -o ${OUTPUT}\n```\n\nThe above example declares two dependencies from `myservice.build` to\n`my_library_a.build` and `my_library_b.build`. Consequently, if a user entered\n`zim run build -c myservice`, Zim will first build the two libraries, and only\nwhen those complete successfully will it build `myservice`.\n\nWhen declaring a requirement, if the Component is omitted, then it is assumed\nto be referring to another named Rule in the current Component.\n\n## Source Dependencies\n\nIn the case of one component depending on another's source code, the exported\nsource files can be advertised. The following example declares `source` as a\nnamed export from `my_go_lib`:\n\n```yaml\nname: my_go_lib\nexports:\n  source:\n    resources:\n    - go.mod\n    - go.sum\n    - \"**/*.go\"\n    ignore:\n    - \"**/*_test.go\"\n```\n\nThat exported source can then be declared as a dependency of a binary:\n\n```yaml\nname: my_exe\nrules:\n  build:\n    requires:\n      - component: my_go_lib\n        export: source\n```\n\nRequiring an export in this way incorporates all files from the export into\nthe component's rule key.\n\n## Build Variables\n\nRules are able to leverage environment variables from two sources. First,\nenvironment variables may be defined at the Component level, which makes them\navailable to all rules of the Component:\n\n```yaml\nname: myservice\nenvironment:\n  RETRY_COUNT: 3\n  FOO: bar\n```\n\nSecond, a handful of environment variables are automatically injected to provide\nRule commands some context:\n\n * `COMPONENT` - the Component name, e.g. \"myservice\"\n * `NAME` - the Component name, e.g. \"myservice\"\n * `KIND` - the Component kind, e.g. \"go\"\n * `RULE` - the Rule name, e.g. \"build\"\n * `NODE_ID` - ID in Graph for the Rule, e.g. \"myservice.build\"\n * `INPUT` - the relative path to the first input\n * `OUTPUT` - the relative path to the first output\n * `OUTPUTS` - relative paths to all outputs (space separated)\n * `DEP` - the relative path to the first dependency\n * `DEPS` - relative paths to all dependencies (space separated)\n * `ARTIFACTS_DIR` - absolute path to directory where outputs are placed\n * `ARTIFACT` - absolute path to the first output\n * `ROOT` - absolute path to the root of the project\n\nAs a trivial example, if a Rule lists \"*.go\" as an input and the Component has\none Go file in the directory named \"main.go\", then `INPUT=main.go` is set in\nthe Rule environment.\n\n## Built-in Rule Commands\n\nZim offers some built-in commands that may be leveraged within rules. To use\nthese, specify `commands` as a list in a rule definition instead of a simple\n`command` string. Here is an example showing how to create a zip file containing\nthe contents of the `dist` directory in a build:\n\n```yaml\nrules:\n  build:\n    inputs:\n      - src/**\n      - package.json\n    outputs:\n      - ${NAME}.zip\n    commands:\n      - cleandir: dist\n      - run: yarn run build\n      - zip:\n          cd: dist\n          input: \".\"\n          output: ${ARTIFACT}\n```\n\nAvailable built-ins:\n\n * `run` - runs the following commands in a shell\n * `mkdir` - creates a directory and its parents as needed (mkdir -p)\n * `cleandir` - removes and recreates the directory (rm -rf then mkdir -p)\n * `remove` - removes files or directories (rm -rf)\n * `move` - relocate files or directories (mv)\n   * `src` - source locations\n   * `dst` - destination locations\n * `copy` - copy files or directories (cp -R)\n   * `src` - source locations\n   * `dst` - destination locations\n   * `options` - cp command options (default `-R`)\n * `zip` - create a zip archive\n   * `options` - zip command options (default `-qrFS`)\n   * `input` - path to input files (default `.`)\n   * `output` - required zip output path\n   * `cd` - optional directory to cd into before running the command\n * `unzip` - unzip an archive\n   * `options` - unzip command options (default `-qo`)\n   * `input` - path to the zip file\n   * `output` - optional directory to extract into\n * `archive` - create a tgz archive\n   * `options` - tar command options (default `-czf`)\n   * `input` - required path(s) to input files\n   * `output` - required path to output tgz\n * `unarchive` - unpack a tgz archive\n   * `options` - tar command options (default `-xzf`)\n   * `input` - path to the tgz\n   * `output` - optional directory to extract into\n\nThese built-ins execute on the build host, not in the container, when a\nComponent is Docker-enabled. This is helpful to avoid I/O performance penalties\nwith Docker on MacOS for example.\n\n## Commands in the CLI\n\nHere are the most commonly used commands.\n\nRun all `build` rules in the Project with the following. Note that `build` is an\narbitrary rule name with no special behavior.\n\n```shell\n$ zim run build\n```\n\nRun the `clean` rule for two specific Components:\n\n```shell\n$ zim run clean -c comp1,comp2\n```\n\nBuild a Component with the cache disabled:\n\n```shell\n$ zim run build --cache disabled -c comp1\n```\n\nShow the rule cache key for a specific Component and Rule:\n\n```shell\n$ zim key -r myservice.build\n```\n\nShow the detailed contents of a rule cache key:\n\n```shell\n$ zim key -r myservice.build --detail\n```\n\nShow all Components in the Project:\n\n```shell\n$ zim list components\n```\n\nShow all input files used by a Component:\n\n```shell\n$ zim list inputs -c myservice\n```\n\nCreate a new authentication token during setup:\n\n```shell\n$ zim add token\n```\n\n## Shell Completions\n\nAuto-completion is available for Components, Rules, and Kinds. Run the following\nfor instructions:\n\n```shell\n$ zim completion -h\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffugue%2Fzim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffugue%2Fzim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffugue%2Fzim/lists"}