gear-rules(5)

GEAR-RULES(5)

File Formats

GEAR-RULES(5)

NAME

gear-rules - rule file for gear

DESCRIPTION

The rule file specifies actions of gear(1) required to extract source files from the package repository.

FORMAT

A rule file consists of 0 or more lines of the following format:

directive: arguments...

Empty lines and lines beginning with “#” are ignored. Directive arguments are delimited by whitespace characters. Whitespaces between the directive name and “:” are optional; whitespaces between “:” and the first argument are also optional. Arguments may contain special characters quoted using shell-alike quoting. There is no support for line continuation.

PATHS

Unless specified otherwise, all paths used in the rule file are relative to the main tree, which is a subtree of the main commit specified by the -t option to gear(1). Paths are not allowed to contain “..”, and therefore can refer only to objects inside the main tree.

However, some directives can accept a tree_path, which can be either a plain path relative to the main tree, or a path with an explicit base tree specification:

base_tree:path_in_tree

The base_tree part can be in one of the following forms:

–: A single period character “.” specifies the main tree. In most cases just omitting the “base_tree:” part gives the same effect; adding “.:” explicitly is required only if the path_in_tree part itself contains the “:” character.
–: A full SHA-1 object name of a commit (40 hex characters) specifies the root tree of that commit. The specified commit must be an ancestor of the main commit.
–: A name of a tag listed in the tag list specifies the root tree of the commit pointed to by the specified tag (directly or indirectly through a chain of tag objects). The specified commit must be an ancestor of the main commit, and all tag objects in the chain must be stored in the tag directory.

The restrictions on references to other commits ensure that a correct git repository which contains the main commit also contains everything which is required to extract source files from the repository.

KEYWORDS

Arguments of some directives can contain keywords in the @keyword@ format, which are replaced by real values before use. Values for keywords can be obtained from the main spec file or from other arguments of the same directive.

The following keywords are available in all directives which perform keyword replacement:

@name@: Package name extracted from spec file.
@version@: Package version extracted from spec file.
@release@: Package release extracted from spec file.

Other keywords are specific to each directive.

DIRECTIVES

spec: path_to_file: Specify path of the main spec file within the main tree. This directive may be omitted if the main spec file is the only file in the main tree which matches the *.spec glob pattern; in this case gear(1) can find the spec file automatically.
tags: path_to_directory: Specify another path of the directory with the list of named tags and stored tag objects instead of .gear-tags and .gear/tags.
type: spec_type: Specify the type of the spec file instead of an unspecified default. This information is saved in the volume header of the output tar archive produced by gear(1).
copy: glob_pattern...: Copy files matching the specified glob patterns to the output directory, except files which match any of glob patterns specified by exclude directives. Every glob_pattern must match at least one file in the main tree.

: Glob patterns specified in this directive may contain multiple directory components separated by “/”. Wildcards are interpreted only in the last component of the pattern.

gzip: glob_pattern...
bzip2: glob_pattern...
lzma: glob_pattern...
xz: glob_pattern...
zstd: glob_pattern...: Like copy, but additionally compress the copied files with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the copied file name.
compress: type=TYPE [name=NAME] [options] -- glob_pattern...: Like copy, but can additionally compress the copied files with TYPE method.

type=TYPE: Specify compression method. Supported values are: copy, bzip2, gzip, lzma, xz, and zstd.
name=<NAME>: Specify destination file name in output directory. In this case glob_pattern should match only one file.

: All methods except copy accept compress options.

copy?: glob_pattern...
gzip?: glob_pattern...
bzip2?: glob_pattern...
lzma?: glob_pattern...
xz?: glob_pattern...
zstd?: glob_pattern...
compress?: type=TYPE [name=NAME] [options] -- glob_pattern...: Like the corresponding directives without “?”, but unmatched patterns are ignored instead of causing errors.
exclude: glob_pattern...: Ignore files matching the specified glob patterns in all copy-like directives. Affects all directives in the rule file irrespective of the order. Specifying a glob pattern which does not match any files in the tree is not an error.

: When copying files from subdirectories of the main tree, the whole path including the subdirectory name is matched against exclude patterns. The “/” characters in the path are not treated as special and can be matched by wildcards.

tar: tree_path [options...]: Create a tar(1) archive of the tree specified by tree_path. The specified tree must exist.

: Valid options are:

spec=path_to_file: Use another file instead of the main spec file to define keyword values.
name=archive_name: Set name of the tar archive. The .tar suffix is added automatically unless another suffix is specified by the suffix option.

: The default value of this option is @dir@-@version@, unless the path part of tree_path is “.”, in which case the default is @name@-@version@.

base=base_name: Add base_name as a leading path to all files in the generated archive. If this option is not specified, by default the archive name without the suffix (set by the name option) is used.
suffix=suffix: Add suffix to the archive file name instead of the default .tar suffix.
exclude=glob_pattern: All files matching the glob_pattern are excluded from the generated tar file. This option can be specified multiple times. The glob_pattern syntax is described in glob section of /usr/share/doc/git/user-manual.html.

: Values of the name and base options and tree_path can contain keywords. In addition to the common keywords, the following keyword is supported:

@dir@: Expands to basename(path(tree_path)). Not allowed when path(tree_path) is “.” and must not be used in the path part of tree_path.

tar.gz: tree_path [options...]
tar.bz2: tree_path [options...]
tar.lzma: tree_path [options...]
tar.xz: tree_path [options...]
tar.zst: tree_path [options...]: Like tar, but additionally compress the generated tar archive with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the archive file name (unless the suffix option is specified, which overrides both the .tar part and the suffix for the compression method).
zip: tree_path [options...]: Like tar, but create a zip(1) archive instead of tar(1) and add the .zip suffix to the archive file name instead of .tar.
tar?: tree_path [options...]
tar.gz?: tree_path [options...]
tar.bz2?: tree_path [options...]
tar.lzma?: tree_path [options...]
tar.xz?: tree_path [options...]
tar.zst?: tree_path [options...]
zip?: tree_path [options...]: Like the corresponding directives without “?”, but do not fail if the path specified in tree_path is not present in the tree. However, if tree_path specifies a non-default base tree, this tree still must be valid.
diff: old_tree_path new_tree_path [options...]: Create a diff in the unified format between trees specified by old_tree_path and new_tree_path. Both trees must exist.

: Valid options are:

spec=path_to_file: Use another file instead of the main spec file to define keyword values.
name=diff_name: Set name of the generated diff file. The .patch suffix must be specified explicitly if required.

: The default name is @new_dir@-@version@-@release@.patch, unless the path part of new_tree_path is “.”, in which case the default is @name@-@version@-@release@.patch.

exclude=glob_pattern: All files matching the glob_pattern are excluded from the generated tar file. This option can be specified multiple times. The glob_pattern syntax is described in glob section of /usr/share/doc/git/user-manual.html.

: Value of the name option and the base tree components of old_tree_path and new_tree_path can contain keywords. In addition to the common keywords, the following keywords are supported:

@old_dir@: Expands to basename(path(old_tree_path)). Not allowed when path(old_tree_path) is “.”.
@new_dir@: Expands to basename(path(new_tree_path)). Not allowed when path(new_tree_path) is “.”.

diff.gz: old_tree_path new_tree_path [options...]
diff.bz2: old_tree_path new_tree_path [options...]
diff.lzma: old_tree_path new_tree_path [options...]
diff.xz: old_tree_path new_tree_path [options...]
diff.zst: old_tree_path new_tree_path [options...]: Like diff, but additionally compress the generated diff file with gzip(1), bzip2(1), lzma(1), xz(1), or zstd(1), and add the appropriate suffix to the diff file name.
diff?: old_tree_path new_tree_path [options...]
diff.gz?: old_tree_path new_tree_path [options...]
diff.bz2?: old_tree_path new_tree_path [options...]
diff.lzma?: old_tree_path new_tree_path [options...]
diff.xz?: old_tree_path new_tree_path [options...]
diff.zst?: old_tree_path new_tree_path [options...]: Like the corresponding directives without “?”, but do not fail if paths specified by old_tree_path or new_tree_path are not present in the tree. However, if old_tree_path or new_tree_path specify non-default base trees, these trees still must be valid.
specsubst: variables...: Specify whitespace-separated list of variables that should be substituted in specfile. Variable names may contain letters, digits and underscore characters. For each variable every occurrence of @variable@ in specfile is substituted with its value. Values for these variables are obtained from the tag object passed to gear(1), therefore a tag object is required when specsubst: directive is used.

SPECSUBST TAG FORMAT

A tag object may contain definitions for variables to be substituted during specsubst: directive processing. These definitions have the following format:

X-gear-specsubst: variable=value

Values are treated literally, there is no support of quoting or line continuation.

EXAMPLES

Archive with modified sources

A simple rule file can contain just a single tar directive to archive everything in the tree:

tar: .

If the project has a separate upstream, adding @release@ to the archive name is recommended to make the name different from upstream:

tar: . name=@name@-@version@-@release@

Archive with unmodified sources and patch with local modifications

If you prefer to create a tar archive with unmodified upstream sources and a separate patch with local modifications, you need to create a tag for the commit with upstream sources (or use the upstream tag if upstream also uses git), specify the tag name in the rule file and store this tag in the repository using gear-store-tags(1). In this case the default archive name used by the tar directive should be correct, unless the package name or version format is different from upstream.

Usually the tag name can be based on the package version:

tar: v@version@:.
diff: v@version@:. .

(other tag naming conventions may be used, like @name@-@version@ or plain @version@). However, if a prerelease version is packaged, parts like “preN” or “rcN” should not be included in the package version, therefore the rule file will need some modifications for such versions.

You may want to exclude .gear subdirectory and spec file from diff generation:

tar: v@version@:.
diff: v@version@:. . exclude=.gear/** exclude=*.spec

Archive with unmodified sources and separate patch files

If you prefer to maintain patch files for local modifications instead of committing modified source files to the git repository, you can store unmodified upstream sources in a subdirectory of the main tree and put patch files directly into the main tree:

tar: package_name
copy: *.patch

This layout is used by gear-srpmimport(1). The gear-update(1) utility can be used to update sources stored in the git repository to a new upstream release.

If you don't like lots of patch files cluttering the main tree, you can move them into a subdirectory:

tar: package_name
copy: patches/*.patch

FILES

.gear-rules, .gear/rules: The list of file names where gear(1), gear-commit(1), gear-create-tag(1), gear-srpmimport(1) and gear-store-tags(1) expect to find rules (first non-empty file from this list is used), unless another name is specified by the --rules=filename option.

AUTHOR

This manual page written by Sergey Vlasov <vsu@altlinux.org>.

Authors and contributors of the programs included in the gear package are listed in the manual pages for these programs.