📖
Docs
Target, artifact and command referencing
This page describes the different types of references used in Earthly:
- Target references:
<project-ref>+my-target - Artifact references:
<project-ref>+my-target/my-artifact.bin - Image references (same as target references)
- Command references:
<project-ref>+MY_COMMAND - Project references (the prefix of the above references):
github.com/foo/bar,./my/local/path
Target reference
Target references point to an Earthly target. They have the general form
<project-ref>+<target>Target references distinguish themselves from command references (see below) by having a name in all-lower-case, kebab-case (e.g.
+my-target).Here are some examples:
+build./js+depsgithub.com/earthly/earthly:v0.1.0+earthlyearthly+for-linux
Artifact reference
Artifact references are similar to target references, except that they have an artifact path at the end. It has the following form
<target-ref>/<artifact-path>Here are some examples:
+build/my-artifact+build/some/artifact/deep/in/a/dir./js+build/distgithub.com/earthly/earthly:v0.1.0+earthly/earthly
Image reference
Because there can only be one image per target, image references have the exact same format as target references.
The only difference is the context where they are used. For example, a
FROM command takes an image reference. While a BUILD command takes a target reference.Command reference
Command references point to a user-defined command (UDC) in an Earthfile. They have the general form
<project-ref>+<command>Command references distinguish themselves from target references by having a name in all-caps, snake-case (e.g.
+MY_COMMAND).Here are some examples:
+COMPILE./js+NPM_INSTALLgithub.com/earthly/earthly:v0.1.0+DOWNLOAD_DIND
Project references
Target and artifact reference syntax
Project references appear in target, artifact and command references. They point to the Earthfile containing the respective target, artifact or command. Below are the different types of project references available in Earthly.
Local, internal
The simplest form, is where a target, command or artifact is referenced from the same Earthfile. In this case, the project reference is simply the empty string. Here are some examples of this type of project reference being used in various other references:
Project ref
Target ref
Artifact ref
Command ref
(empty string)
+<target-name>+<target-name>/<artifact-path>+<command-name>(empty string)
+build+build/out.bin+COMPILEIn this form, Earthly will look for the target within the same Earthfile. We call this type of referencing local, internal. Local, because it comes from the same system, and internal, because it is within the same Earthfile.
Local, external
Another form, is where a target, command or artifact is referenced from a different directory. In this form, the path to that directory is specified before
+. It must always start with either ./, ../ or /, on any operating system (including Windows). Example:Project ref
Target ref
Artifact ref
Command ref
./path/to/another/dir./path/to/another/dir+<target-name>./path/to/another/dir+<target-name>/<artifact-path>./path/to/another/dir+<command-name>./js./js+build./js+build/out.bin./js+COMPILEIt is recommended that relative paths are used, for portability reasons: the working directory checked out by different users will be different, making absolute paths infeasible in most cases.
Remote
Another form of a project reference is the remote form. In this form, the recipe and the build context are imported from a remote location. It has the following form:
Project ref
Target ref
Artifact ref
Command ref
<vendor>/<namespace>/<project>/path/in/project[:some-tag]<vendor>/<namespace>/<project>/path/in/project[:some-tag]+<target-name><vendor>/<namespace>/<project>/path/in/project[:some-tag]+<target-name>/<artifact-path><vendor>/<namespace>/<project>/path/in/project[:some-tag]+<command-name>github.com/earthly/earthly/buildkitdgithub.com/earthly/earthly/buildkitd+buildgithub.com/earthly/earthly/buildkitd+build/out.bingithub.com/earthly/earthly/buildkitd+COMPILEgithub.com/earthly/earthly:v0.1.0github.com/earthly/earthly:v0.1.0+buildgithub.com/earthly/earthly:v0.1.0+build/out.bingithub.com/earthly/earthly:v0.1.0+COMPILEImport reference
Finally, the last form of project referencing is an import reference. Import references may only exist after an
IMPORT command, which helps resolve the reference to a full project reference of the types above.Import command
Project ref
Target ref
Artifact ref
Command ref
IMPORT <full-project-ref> AS <import-alias><import-alias><import-alias>+<target-name><import-alias>+<target-name>/<artifact-path><import-alias>+<command-name>IMPORT github.com/earthly/earthly/buildkitdbuildkitdbuildkitd+buildbuildkitd+build/out.binbuildkitd+COMPILEIMPORT github.com/earthly/earthly:v0.1.0earthlyearthly+buildearthly+build/out.binearthly+COMPILEHere is an example in an Earthfile:
1
IMPORT github.com/earthly/earthly/buildkitd
2
3
...
4
5
BUILD buildkitd+buildkitd
Copied!
Implicit Base Target Reference
All Earthfiles start with a base recipe. This is the only recipe which does not have an explicit target name - the name is always implied to be
base. All other target implicitly inherit from base. You can imagine that all recipes start with an implicit FROM +base1
# base recipe
2
FROM golang:1.15-alpine3.13
3
WORKDIR /go-example
4
5
build:
6
# implicit FROM +base
7
RUN echo "Hello World"
Copied!
Canonical form
Most references have a canonical form. It is essentially the remote form of the same target, with repository and tag inferred. The canonical form can be useful as a universal identifier for a target.
For example, depending on where the files are stored, the
+build target could have the canonical form github.com/some-user/some-project/some/deep/dir:master+build, where github.com/some-user/some-project was inferred as the Git location, based on the Git remote called origin, and /some/deep/dir was inferred as the sub-directory where +build exists within that repository. The Earthly tag is inferred using the following algorithm:- If the current HEAD has at least one Git tag, then use the first Git tag listed by Git, otherwise
- If the repository is not in detached HEAD mode, use the current branch, otherwise
- Use the current Git hash.
If no Git context is detected by Earthly, then the target does not have a canonical form.
Last modified 1mo ago