From 8fead40f1c0d32684ac50074ecbdd9fd7a6c74a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roman=20Smr=C5=BE?= Date: Sun, 21 Dec 2025 21:43:35 +0100 Subject: Documentation for checkouts and destinations --- README.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 109 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ceb8255..f260f67 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ or for any manually given commit range. Job definition -------------- -The top-level elements of the YAML file are `job ` defining steps to -perform the job and potentially listing artifacts produced or required. +The basic top-level elements of the YAML file are `job ` defining steps +to perform the job and potentially listing artifacts produced or required. Example: @@ -35,15 +35,24 @@ Each job is a map with the following attributes: `shell` : Shell script to perform the job. -`artifact ` (optional) +`artifact ` : Defines artifact `` produced by this job. Is itself defined as a dictionary. `artifact .path` : Path to the produced artifact file, relative to the root of the project. -`uses` (optional) +`uses` : List of artifact required for this job, in the form `.`. +`checkout` +: List of repositories to checkout into the work directory before starting + the job (see below). If not specified, the default repository (containing + the YAML file) will be checked out to the root of the work directory. + +`publish` +: List of artifacts (produced by this or other jobs) to publish to specified + destinations (see below). + Usage ----- @@ -85,3 +94,99 @@ minici run --new-tags= ``` The above options `--range`, `--since-upstream`, etc can be arbitrarily combined. + + +Explicit script file +-------------------- + +Normally, `minici` uses the `minici.yaml` file from the repository in the current working directory; +the path to a repository used can also be specified on the command line before the command (e.g. `run`). +That path must contain a slash character to disambiguate it from a command name, e.g.: +``` +minici ../path/to/some/other/repo run some_job +``` + +Whether using the implicit repository or one specified on the command line, when +executing jobs for a range of commits, `minici` uses the `minici.yaml` file +version from each individual commit. So for example, running: +``` +minici run HEAD~5..HEAD +``` +can execute different jobs for each commit, if the job file was changed in each of the last five commits. + +To force usage of particular version of `minici.yaml` file, explicit path to that file can be given: +``` +minici ./minici.yaml run HEAD~5..HEAD +``` +In this case, the jobs specified in the current version of `minici.yaml` will +be used for all of the five commits. + + +Additional repositories and checkouts +------------------------------------- + +Jobs can also use repositories other than the default one (which contains the `minici.yaml` file). +The additional repositories need to be declared at the top level of the `minici.yaml` file as: +``` +repo : + path: (optional, only relevant for explicit script file) +``` + +The path of a repository `` can be given (or overridden) on command line by passing argument in the form `--repo=:` before the command name. +To explicitly set what repositories to check out, set the list in the `checkout` element of the job definition: + +``` +job some_job: + checkout: + - repo: some_repo + dest: destination/path + ... +``` + +The elements of the `checkout` list are dictionaries with following elements: + +`repo` +: Name of the repo to checkout from. If not given, the default repo (containing the `minici.yaml` file) is used. + +`dest` +: Path within the work directory to use for the checkout. If not given, the root of the work directory is used. + +`subtree` +: If provided, checkout only given subtree of the repository. If the given path does not exist within a particular commit, the checkout and the whole job fail. + +All checkouts are performed before running the script given in the `shell` element. +If no `checkout` list is given, the whole default repo is checked out to the root of the work directory. + + +Destinations +------------ + +Apart from a recipe, a job can also contain instructions to publish artifacts to given destinations. +The artifacts can be produced either by the publishing job or other jobs, and the destination must be declared at the top of the job file: + +``` +destination : + url: (optional, only relevant for explicit script file) +``` + +**Note**: only local filesystem path is currently supported as `url`. + +The URL of a destination `` can be given (or overridden) on command line by passing argument in the form `--destination=:` before the command name. +The artifacts to publish are then given in the `publish` list of a job definition: +``` +job publish_something: + publish: + - to: some_destination + artifact: other_job.some_artifact +``` + +Elements of the `publish` list are dictionaries with following elements: + +`to` +: Name of the destinations to publish to. + +`artifact` +: Artifact to publish—either `` if produced by this job, or `.` if produced by other job. + +`path` +: Path within the destination to publish this artifact to. If not given, artifact path from the work directory is used. -- cgit v1.2.3