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 argu
ments 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 contin
uation.
PATHS
Unless specified otherwise, all paths used in the rule file are rela
tive 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 con
tains 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@ for
mat, 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.
copy: glob_pattern...
Copy files matching the specified glob patterns to the output
directory, except files which match any of glob patterns speci
fied 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...
Like copy, but additionally compress the copied files with
gzip(1), bzip2(1), lzma(1) or xz(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 and xz.
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...
compress?: type=TYPE [name=NAME] [options] -- glob_pattern...
Like the corresponding directives without ?, but unmatched pat
terns 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 irre
spective 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 gen
erated 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.
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...]
Like tar, but additionally compress the generated tar archive
with gzip(1), bzip2(1), lzma(1) or xz(1), and add the appropri
ate 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...]
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.
Value of the name option and the base tree components of
old_tree_path and new_tree_path can contain keywords. In addi
tion to the common keywords, the following keywords are sup
ported:
@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...]
Like diff, but additionally compress the generated diff file
with gzip(1), bzip2(1), lzma(1) or xz(1), and add the appropri
ate 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...]
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.
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 cor
rect, 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, there
fore the rule file will need some modifications for such versions.
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-cr
ate-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.
SEE ALSO
gear(1), gear-srpmimport(1), gear-update(1), gear-store-tags(1).
gear 1.7.3.1 December 2009 GEAR-RULES(5)