{
"files": [
{
"pattern" or "aql": "[Mandatory]",
"target": "[Optional, Default: ./]",
"props": "[Optional]",
"recursive": "[Optional, Default: true]",
"flat": "[Optional, Default: false]",
"build": "[Optional]",
"explode": "[Optional, Default: false]",
"excludePatterns": ["[Optional]"],
"sortBy" : ["[Optional]"],
"sortOrder": "[Optional, Default: 'asc']",
"limit": [Optional],
"offset": [Optional]
}
]
}
Where:
Element | Description |
|---|---|
pattern | [Mandatory if 'aql' is not specified] |
target | [Optional] For flexibility in specifying the target path, you can include placeholders in the form of |
aql | [Mandatory if 'pattern' is not specified] |
props | [Optional] |
flat | [Default: false] |
recursive | [Default: true] |
build | [Optional] The property format is build-name/build-number. If the build number is not specified, or the keyword LATEST is used for the build number, then the latest published build number is used. |
explode | [Default: false] If true, the downloaded archive file is extracted after the download. The archived file itself is deleted locally. The supported archive types are: zip, tar; tar.gz; and tgz |
excludePatterns | [Optional. Applicable only when 'pattern' is specified] An array (enclosed with square brackets) of patterns to be excluded from downloading. Unlike the "pattern" property, "excludePatterns" must NOT include the repository as part of the pattern's path. You can use wildcards to specify multiple artifacts. For example: ["*.sha1","*.md5"] |
| sortBy | [Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation. |
| sortOrder | [Default: asc] The order by which fields in the sortBy option should be sorted. Accepts asc or desc. |
| limit | [Optional] The maximum number of items to fetch. Usually used with the sortBy option. |
| offset | [Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the sortBy option. |
Currently sortBy, sortOrder, limit and offset are not supported in TeamCity.
Upload Spec Schema
{
"files": [
{
"pattern": "[Mandatory]",
"target": "[Mandatory]",
"props": "[Optional]",
"recursive": "[Optional, Default: 'true']",
"flat" : "[Optional, Default: 'true']",
"regexp": "[Optional, Default: 'false']",
"explode": "[Optional, Default: false]",
"excludePatterns": ["[Optional]"]
}
]
}
Where:
Element | Description |
|---|---|
pattern | [Mandatory] Specifies the local file system path to artifacts which should be uploaded to Artifactory. You can specify multiple artifacts by using wildcards or a regular expression as designated by the regexp property. |
target | [Mandatory] Specifies the target path in Artifactory in the following format: [repository_name]/[repository_path] If the pattern ends with a slash, for example "repo-name/a/b/", then "b" is assumed to be a folder in Artifactory and the files are uploaded into it. In the case of "repo-name/a/b", the uploaded file is renamed to "b" in Artifactory. For flexibility in specifying the upload path, you can include placeholders in the form of |
props | [Optional] |
flat | [Default: true] |
recursive | [Default: true] |
regexp | [Default: false] If true, the command will interpret the pattern property, which describes the local file-system path of artifacts to upload, as a regular expression. If false, the command will interpret the pattern property as a wild-card expression. |
explode | [Default: false] If true, the uploaded archive file is extracted after it is uploaded. The archived file itself is not saved in Artifactory. The supported archive types are: zip, tar; tar.gz; and tgz |
excludePatterns | [Optional] An array (enclosed with square brackets) of patterns to be excluded from uploading. Allows using wildcards or a regular expression as designated by the regexp property. If you use a regexp, you need to escape any reserved characters (such as ".", "?", etc.) used in the expression using a backslash "\". For example: ["*.sha1","*.md5"] |
Using Placeholders
File Specs offer enormous flexibility in how you upload, or download files through use of wildcard or regular expressions with placeholders.
Any wildcard enclosed in parenthesis in the pattern property can be matched with a corresponding placeholder in the target property to determine the name of the artifact once downloaded or uploaded. The following example downloads all zip files, located under the root path of the my-local-repo repository, which include a dash in their name. The files are renamed when they are downloaded, replacing the dash with two dashes.
{
"files": [
{
"pattern": "my-local-repo/(*)-(*).zip",
"target": "froggy/{1}--{2}.zip",
"recursive": "false"
}
]
}
Examples
Example 1: Download all files located under the all-my-frogs directory in the my-local-repo repository to the froggy/all-my-frogs directory.
{
"files": [
{
"pattern": "my-local-repo/all-my-frogs/",
"target": "froggy/"
}
]
}
Example 2: Download all files retrieved by the AQL query to the local/output directory.
{
"files": [
{
"aql": {
"items.find": {
"repo": "my-local-repo",
"$or": [
{
"$and": [
{
"path": {
"$match": "."
},
"name": {
"$match": "a1.in"
}
}
]
},
{
"$and": [
{
"path": {
"$match": "*"
},
"name": {
"$match": "a1.in"
}
}
]
}
]
}
},
"target": "local/output/"
}
]
}
Example 3: Upload
- All zip files located under the
resourcesdirectory to thezipfolder, under the all-my-frogs repository.
AND - All TGZ files located under the
resourcesdirectory to the tgz folder, under the all-my-frogs repository. - Tag all zip files with type = zip and status = ready.
- Tag all tgz files with type = tgz and status = ready.
{
"files": [
{
"pattern": "resources/*.zip",
"target": "my-repo/zip/",
"props": "type=zip;status=ready"
},
{
"pattern": "resources/*.tgz",
"target": "my-repo/tgz/",
"props": "type=tgz;status=ready"
}
]
}
Example 4: Download all files located under the all-my-frogs directory in the my-local-repo repository except for the '.zip' files and the 'props.' files
{
"files": [
{
"pattern": "my-local-repo/all-my-frogs/",
"excludePatterns": [
"*.zip",
"all-my-frogs/props.*"
]
}
]
}
Example 5: Download three oldest zip files from the my-local-repo repository, into local/output directory.
{
"files": [
{
"pattern": "my-local-repo/*.zip",
"sortBy": ["created"],
"limit": 3,
"target": "local/output/"
}
]
}
Example 6: Download three oldest zip files from the my-local-repo repository, into local/output directory. This File Spec uses AQL.
{
"files": [
{
"aql": {
"items.find": {
"repo": "my-local-repo",
"$or": [
{
"$and": [
{
"path": {
"$match": "*"
},
"name": {
"$match": "*.zip"
}
}
]
}
]
}
},
"sortBy": ["created"],
"limit": 3,
"target": "local/output/"
}
]
}
Example 7: Download the artifacts from the generic-local repository, which belong to the following build, which had been published to Artifactory - Build name: my-build and build number: 10.
{
"files": [
{
"pattern": "generic-local",
"build": "my-build/10"
}
]
}
Example 8: Download the artifacts from the generic-local repository, which belong to the my-build build, which had been published to Artifactory. The artifacts of the latest build number published to Artifactory will be downloaded.
{
"files": [
{
"pattern": "generic-local",
"build": "my-build"
}
]
}
Schema Validation
JSON schemas allow you to annotate and validate JSON files. The JFrog File Spec schema is available in the JSON Schema Store catalog and in the following link: https://github.com/jfrog/jfrog-cli/blob/v2/schema/filespec-schema.json.
Using Jetbrains IDEs (Intellij IDEA, Webstorm, Goland, etc...)?
The File Spec schema automatically applied on the following file patterns:
**/filespecs/*.json
*filespec*.json
*.filespec
Using Visual Studio Code?
To apply the File Spec schema validation, install the JFrog VS-Code extension.
Alternatively, copy the following to your settings.json file:
"json.schemas": [
{
"fileMatch": ["**/filespecs/*.json", "*filespec*.json", "*.filespec"],
"url": "https://raw.githubusercontent.com/jfrog/jfrog-cli/v2/schema/filespec-schema.json"
}
]
