Note: the filter file that this page documents is deprecated. Please instead see “Filtering with the download mode file” for updated instructions on how to filter modules in Athens.
The proxy supports the following three use cases
These settings can be done by creating a configuration file which can be pointed by setting either
config.dev.toml or setting
ATHENS_FILTER_FILE as an environment variable.
Every line of the configuration can start either with a
+denoting that the module has to be included by the proxy
Ddenoting that the module has to be fetched directly from an upstream proxy and not stored locally
-denoting that the module is excluded and will not be fetched into the proxy or from the upstream proxy
It allows for
# to add comments and new lines are skipped. Anything else would result in an error
# This is a comment - github.com/azure + github.com/azure/azure-sdk-for-go # get golang tools directly D golang.org/x/tools
In the above example,
golang.org/x/tools is fetched directly from the upstream proxy. All the modules from
github.com/azure are excluded except
The list of modules can grow quickly in size and sometimes may want to specify configuration for a handful of modules. In this case, they can set a default mode for all the modules and add specific rules to certain modules that they want to apply to. The default rule is specified at the beginning of the file. It can be an either
An example default mode is
D - github.com/manugupt1/athens + github.com/gomods/athens
In the above example, all the modules are fetched directly from the source.
github.com/manugupt1/athens is excluded and
github.com/gomods/athens is stored in the proxy storage.
Using an “approved list” is a common practice that requires each minor or patch version to be approved before it is allowed in the codebase. This is accomplished by adding a list of version patterns to the rule. These version patterns are comma-separated and prefix-matching, so
v2.3.* both match the requested version
An example version filter is
- # use internal github enterprise server directly D enterprise.github.com/company # external dependency approved list + github.com/gomods/athens v0.1,v0.2,v0.4.1
In the above example, any module not in the rules will be excluded. All modules from
enterprise.github.com/company are fetched directly from the source. The
github.com/gomods/athens module will be stored in the proxy storage, but only for version
v0.4.1 and any patch versions under
v0.2 minor versions.
Athens provides advanced filter modifiers to cover cases such as API compatibility or when a given dependency changes its license from a given versions. The modifiers are intended to be used in the pattern list of the filter file.
- # external dependency approved list + github.com/gomods/athens
The currently supported modifiers are
~1.2.3will enable all patch versions from 1.2.3 and above (e.g. 1.2.3, 1.2.4, 1.2.5)
x >= 3
^1.2.3will enable all patch and minor versions from 1.2.3 and above (e.g. 1.2.4, 1.3.0 and 1.4.5)
x >= 2and
y >= 3
<1.2.3will enable all versions lower than 1.2.3 (e.g. 1.2.2, 1.0.0 and 0.58.9)
x <= 1,
y < = 2and
z < 3
This kind of modifiers will work only if a three parts semantic version is specified. For example,
~4.5.6will work while