From 2b7e580be069d30b86bb8633c57c653a0a328b81 Mon Sep 17 00:00:00 2001 From: Markus Lehtonen Date: Tue, 27 May 2014 10:09:36 +0300 Subject: [PATCH] docs: manpages for the rpm tools Signed-off-by: Markus Lehtonen --- docs/Makefile | 5 + docs/common.ent | 7 + docs/main.sgml | 2 + docs/man.gbp-buildpackage-rpm.sgml | 12 + docs/man.gbp-import-orig-rpm.sgml | 11 + docs/man.gbp-import-srpm.sgml | 11 + docs/man.gbp-pq-rpm.sgml | 11 + docs/man.gbp-rpm-ch.sgml | 11 + docs/manpages/gbp-buildpackage-rpm.sgml | 764 ++++++++++++++++++++++++++++++++ docs/manpages/gbp-import-orig-rpm.sgml | 324 ++++++++++++++ docs/manpages/gbp-import-srpm.sgml | 262 +++++++++++ docs/manpages/gbp-pq-rpm.sgml | 399 +++++++++++++++++ docs/manpages/gbp-rpm-ch.sgml | 406 +++++++++++++++++ docs/manpages/man.seealso-rpm.sgml | 12 + docs/manpages/manpages-rpm.ent | 10 + docs/manual-rpm.sgml | 8 + packaging/git-buildpackage.spec | 7 + 17 files changed, 2262 insertions(+) create mode 100644 docs/man.gbp-buildpackage-rpm.sgml create mode 100644 docs/man.gbp-import-orig-rpm.sgml create mode 100644 docs/man.gbp-import-srpm.sgml create mode 100644 docs/man.gbp-pq-rpm.sgml create mode 100644 docs/man.gbp-rpm-ch.sgml create mode 100644 docs/manpages/gbp-buildpackage-rpm.sgml create mode 100644 docs/manpages/gbp-import-orig-rpm.sgml create mode 100644 docs/manpages/gbp-import-srpm.sgml create mode 100644 docs/manpages/gbp-pq-rpm.sgml create mode 100644 docs/manpages/gbp-rpm-ch.sgml create mode 100644 docs/manpages/man.seealso-rpm.sgml create mode 100644 docs/manpages/manpages-rpm.ent diff --git a/docs/Makefile b/docs/Makefile index 5cd83a0..cd65701 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,6 +3,7 @@ MAN1S = \ gbp \ gbp-buildpackage \ + gbp-buildpackage-rpm \ gbp-clone \ gbp-config \ gbp-create-remote-repo \ @@ -10,8 +11,12 @@ MAN1S = \ gbp-import-dsc \ gbp-import-dscs \ gbp-import-orig \ + gbp-import-orig-rpm \ + gbp-import-srpm \ gbp-pq \ + gbp-pq-rpm \ gbp-pull \ + gbp-rpm-ch \ $(NULL) MAN5S = gbp.conf diff --git a/docs/common.ent b/docs/common.ent index 69a703f..6fc532c 100644 --- a/docs/common.ent +++ b/docs/common.ent @@ -24,11 +24,18 @@ debuild"> gbp.conf"> + Markus"> + Lehtonen"> + markus.lehtonen@linux.intel.com"> + + 1"> gbp buildpackage-rpm"> gbp import-orig-rpm"> gbp import-srpm"> gbp pq-rpm"> + gbp rpm-ch"> rpmbuild"> + wget"> Debian"> Git"> diff --git a/docs/main.sgml b/docs/main.sgml index bd1d97d..7689bf7 100644 --- a/docs/main.sgml +++ b/docs/main.sgml @@ -6,6 +6,8 @@ %VERSION; %MANPAGES; + + %MANPAGES.RPM; %CHAPTERS; diff --git a/docs/man.gbp-buildpackage-rpm.sgml b/docs/man.gbp-buildpackage-rpm.sgml new file mode 100644 index 0000000..8752d57 --- /dev/null +++ b/docs/man.gbp-buildpackage-rpm.sgml @@ -0,0 +1,12 @@ + + %COMMON; + + %MANPAGES; +]> + + +git-buildpackage-rpm Manual +&man.gbp.buildpackage.rpm; + diff --git a/docs/man.gbp-import-orig-rpm.sgml b/docs/man.gbp-import-orig-rpm.sgml new file mode 100644 index 0000000..621b11d --- /dev/null +++ b/docs/man.gbp-import-orig-rpm.sgml @@ -0,0 +1,11 @@ + + %COMMON; + + %MANPAGES; +]> + + +git-buildpackage-rpm Manual +&man.gbp.import.orig.rpm; + diff --git a/docs/man.gbp-import-srpm.sgml b/docs/man.gbp-import-srpm.sgml new file mode 100644 index 0000000..7efd8b1 --- /dev/null +++ b/docs/man.gbp-import-srpm.sgml @@ -0,0 +1,11 @@ + + %COMMON; + + %MANPAGES; +]> + + +git-buildpackage-rpm Manual +&man.gbp.import.srpm; + diff --git a/docs/man.gbp-pq-rpm.sgml b/docs/man.gbp-pq-rpm.sgml new file mode 100644 index 0000000..1161508 --- /dev/null +++ b/docs/man.gbp-pq-rpm.sgml @@ -0,0 +1,11 @@ + + %COMMON; + + %MANPAGES; +]> + + +git-buildpackage-rpm Manual +&man.gbp.pq.rpm; + diff --git a/docs/man.gbp-rpm-ch.sgml b/docs/man.gbp-rpm-ch.sgml new file mode 100644 index 0000000..63fed8d --- /dev/null +++ b/docs/man.gbp-rpm-ch.sgml @@ -0,0 +1,11 @@ + + %COMMON; + + %MANPAGES; +]> + + +git-buildpackage-rpm Manual +&man.gbp.rpm.ch; + diff --git a/docs/manpages/gbp-buildpackage-rpm.sgml b/docs/manpages/gbp-buildpackage-rpm.sgml new file mode 100644 index 0000000..b3c9e6c --- /dev/null +++ b/docs/manpages/gbp-buildpackage-rpm.sgml @@ -0,0 +1,764 @@ + + +
+ &rpm-email; +
+ + &rpm-firstname; + &rpm-surname; + + + gbp-buildpackage-rpm + &rpm-mansection; + + + git-buildpackage-rpm + gbp-buildpackage-rpm + Build RPM packages from a Git repository + + + + &gbp-buildpackage-rpm; + + + + + [auto|on|off] + COLOR_SCHEME + [auto|on|off] + =DIRECTORY + =VENDOR + TREEISH + BRANCH_NAME + BRANCH_NAME + + + BUILD_CMD + CLEAN_CMD + + GPG-KEYID + COMMAND + COMMAND + COMMAND + COMMAND + + + TAG-FORMAT + TAG-FORMAT + + + [TAG|BRANCH|TREEISH] + DIRECTORY + LEVEL + PREFIX + DIRECTORY + =DIRECTORY + =DIRECTORY + =DIRECTORY + =DIRECTORY + =DIRECTORY + =DIRECTORY + TREEISH + + DIRECTORY + FILEPATH + + + + + + TREEISH + THRESHOLD + REGEX + COMMITISH + + =TAG_FORMAT + + + + DESCRIPTION + + &gbp-buildpackage-rpm; is used to build RPM packages from a &git; + repository. It is an RPM counterpart for the &gbp-buildpackage; tool that + is designed for building Debian packages. + + + &gbp-buildpackage-rpm; will, in order: + + + + + Verify that it is being executed from the proper location. + + + + + Verify that the repository doesn't contain any uncommitted source + changes. + + + + + Verify that it is being executed from the correct branch. + + + + + Export packaging files to a separate build area. + + + + + Create an orig source tarball if it doesn't exist. + + + + + Call rpmbuild(1) (or the application + specified via ), passing along all + command line arguments that don't start with --git-. + + + + + (Optionally) tag the tree after a successful build. + + + + + (Optionally) call a post build hook - e.g. to run + rpmlint. + + + + + (Optionally) call a post tag hook - e.g. to push the results to a + remote repository after creating the tag. + + + + + + OPTIONS + + + + + + + Don't abort if there are uncommitted changes in the source tree or + the current branch doesn't match the + PACKAGING-BRANCH. + + + + + + + + + Don't abort if there are untracked files in the source tree. + + + + + + + + + Add a git tag after a successful build. + + + + + + + + + Use BUILD_CMD instead of + rpmbuild -ba. + + + + + + + + + Use CLEAN_CMD. + + + + + + + + + Verbose execution + + + + + [auto|on|off] + + + + Whether to use colored output. + + + + + COLOR_SCHEME + + + + Colors to use in output (when color is enabled). The format for + COLOR_SCHEME is + '<debug>:<info>:<warning>:<error>'. + Numerical values and color names are accepted, empty fields imply + the default color. For example --git-color-scheme='cyan:34::' would + show debug messages in cyan, info messages in blue and other messages + in default (i.e. warning and error messages in red). + + + + + [auto|on|off] + + + + Whether to send a desktop notification after the build. + + + + + =DIRECTORY + + + + Base directory under which temporary directories are created. + + + + + =VENDOR + + + + Distribution vendor name. + + + + + =BRANCH_NAME + + + + Branch to build the orig tarball from if + is set to + BRANCH. Default is + upstream. + + + + + =BRANCH_NAME + + + + If you're not on this branch when invoking &gbp-buildpackage-rpm; it + will fail. Default is master. This is done + to make sure you don't accidentally release from a topic branch. Not + being on this branch will be ignored when using + . + + + + + =BRANCH_NAME + + + + Name (format string) of the patch-queue/development branch. This + makes building easier when working with separate packaging and + development branches. + + + If is enabled and + &gbp-buildpackage-rpm; detects that the current branch has a + patch-queue/development branch it exports the patches from there + instead of the tip of the current branch (unless + is defined, of course). + Similarly, if the current branch is a patch-queue/development branch + &gbp-buildpackage-rpm; will automatically enable patch-export and + export packaging files from the packaging branch instead of the + current branch (unless ) is defined. + + + + + + + + + Don't check if the current branch matches + PACKAGING-BRANCH. + + + + + + + + + Include git submodules in the orig tarball. + + + + + + + + + GPG sign all created tags. + + + + + GPG-KEYID + + + + Use this keyid for gpg signing tags. + + + + + COMMAND + + + + Excecute COMMAND after tagging a new + version. + + + Exported environment variables are: GBP_TAG (the name + of the generated tag), GBP_BRANCH (the branch the + package was build from) and GBP_SHA1 (the sha1 of the + commit the tag was created at). + + + + + COMMAND + + + + Execute COMMAND after successful + build. + + + Exported environment variables are: GBP_CHANGES_FILE + (the name of the generated changes file), + GBP_BUILD_DIR (the build dir). + + + + + COMMAND + + + + Execute COMMAND after exporting the source + tree. + + + Exported environment variables are: GBP_GIT_DIR (the + repository the package is being built from), + GBP_TMP_DIR (the temporary directory where the sources + have been initially exported). + + + + + COMMAND + + + + Execute COMMAND from the build directory + before calling rpmbuild or the application + specified via . + + + Exported environment variables are: GBP_GIT_DIR (the + repository the package is being built from), + GBP_BUILD_DIR (the build dir). + + + + + + + + + Enable builder. Note: causes the + postbuild hook to be disabled, too. + + + + + + + + + Enable running all (cleaner, postexport, prebuild, postbuild, and + posttag) hooks. Note: the command is + not affected by this option. + + + + + TAG-FORMAT + + + + Use this tag format when tagging released versions of the package. + + + + + TAG-FORMAT + + + + Use this tag format when looking for tags of upstream versions, + default is upstream/%(version)s. + + + + + + + + + Force creation of an orig tarball (overwriting a pre-existing one if + present). + + + + + + + + + Don't try to create any orig tarball. + + + + + DIRECTORY + + + + Export the packaging files from the current branch head (or the + treeish object given via to + DIRECTORY before building. + + + + + =DIRECTORY + + =DIRECTORY + + =DIRECTORY + + =DIRECTORY + + =DIRECTORY + + =DIRECTORY + + + + Build subdirectory options for rpmbuild builder. Of these + and + also affects where + &gbp-buildpackage-rpm; exports the packaging files under the export + directory. + + + + + TREEISH + + + + Instead of exporting the current branch head, export the treeish + object TREEISH. The special name + INDEX exports the current index, + WC.TRACKED exports all files tracked by + Git in the current working copy as is, + WC.UNTRACKED exports all untracked files + too whereas WC (or + WC.IGNORED) exports all files in the + current working directory, even ignored files. + + + + + + + + + Only export packaging files without running builder. + + + + + DIRECTORY + + + + Subdirectory that contains the RPM packaging files. + + + + + FILEPATH + + + + Relative path to the spec file to use. Special value + auto causes &gbp-buildpackage-rpm; to + search and guess. Other values cause the + option to be ignored: the + directory of the spec file is used, instead. + + + + + [TAG|BRANCH|TREEISH] + + + + How to find the upstream sources used to generate the tarball. + TAG looks at a tag corresponding to the + version in the changelog. BRANCH looks at + the upstream branch given via the + option. Other values are + interpreted as treeishs. + + + This doesn't have any effect if + is being used. + + + + + DIRECTORY + + + + Search for original tarballs in DIRECTORY + instead of generating them. + + + + + LEVEL + + + + Specifies the upstream tarball compression level if an upstream + tarball needs to be built. + + + + + PREFIX + + + + Prefix (directory) to be used when generating tarballs. Special value + auto causes &gbp-buildpackage-rpm; to + guess the prefix. + + + + + + + + + Don't build, only tag and run post-tag hooks. + + + + + + + + + Don't fail tag operations if a tag with the same version already + exists, but, overwrite the existing tag, instead. + + + + + + + + + Use pristine-tar when generating the upstream tarball if it doesn't + exist. + + + + + + + + + Commit the pristine-tar delta to the pristine-tar branch if a new + tarball was generated and the pristine-tar data isn't already there. + + + + + + + + + Create patches from the commits between the upstream version and + export-treeish. That is, after exporting packaging files (from the + pacakging directory) &gbp-buildpackage-rpm; creates one patch per + commit (similar to git-format-patch) and updates the spec file in the + export dir. You use to + specify the tip commit of the patch series. + + + + + TREEISH + + + + Use TREEISH as the tip commit of the patch + series instead of the default - i.e. treeish from which the packaging + files are exported (which is defined with + . + + + + + THRESHOLD + + + + Compress (auto-generated) patches larger than given + THRESHOLD bytes. Special value 0 disabled + patch compression. + + + + + REGEX + + + + Exclude changes to path(s) matching REGEX + in patch generation. + + + + + COMMITISH + + + + Squash commits up to the given COMMITISH + into one monolitic diff. Could be used if one wants to squash commits + from an upstream release up to a stable update into a single diff + (commits on top of the stable would generate one patch per commit as + usual). The format is '<commit_ish>[:<filename_base>]', + i.e. commitish optionally followed by a colon and the desired + filename base for the diff (suffix '.diff' is automatically added by + &gbp-buildpackage-rpm;). Magic word 'HEAD' translates to the + patch-export-treeish when given as the squash-point. This allows one + to configure gbp to always squash all commits into one monolithic + diff. + + + + + + + + + Whether the patch files should start with a number or not. + + + + + =TAG_FORMAT + + + + &gbp-buildpackage-rpm; always automatically sets/updates the 'VCS:' + tag in the spec file after exporting. This option defines the format + string for the 'VCS:' tag. An empty value causes no 'VCS:' tag to be + inserted and possible old 'VCS:' tag to be removed. Otherwise, the + old 'VCS:' tag is updated or a new 'VCS:' tag is added if one does + not exist. In the format string '%(tagname)s' expands to the long tag + name (from git-describe) and '%(commit)s' expans to the sha1 of the + exported commit. + + + + + + + EXAMPLES + + Only build a source RPM with &rpmbuild; + + + &gbp-buildpackage-rpm; -bs + + + Build an RPM package with &rpmbuild; on a custom branch with the uncommitted + changes included. + + + &gbp-buildpackage-rpm; --git-ignore-branch --git-export=WC.UNTRACKED + + + + &man.gbp.config-files; + + All options in the config files are specified without the 'git-' prefix. + + + + SEE ALSO + + , + , + , + , + + rpmbuild + 8 + , + , + &man.seealso.common; + + + + AUTHOR + + &rpm-username; &rpm-email; + + + diff --git a/docs/manpages/gbp-import-orig-rpm.sgml b/docs/manpages/gbp-import-orig-rpm.sgml new file mode 100644 index 0000000..8e2635b --- /dev/null +++ b/docs/manpages/gbp-import-orig-rpm.sgml @@ -0,0 +1,324 @@ + + +
+ &rpm-email; +
+ + &rpm-firstname; + &rpm-surname; + + + + gbp-import-orig-rpm + &rpm-mansection; + + + git-import-orig-rpm + gbp-import-orig-rpm + Import an upstream source into a git repository. + + + + &gbp-import-orig-rpm; + + &man.common.options.synopsis; + =VENDOR + VERSION + + BRANCH-NAME + BRANCH-NAME + DIRECTORY + + TAG-NAME + + GPG-KEYID + TAG-FORMAT + PATTERN + + + + + + + + UPSTREAM-SOURCE + + + + + DESCRIPTION + + &gbp-import-orig-rpm; is an basically identical to the &gbp-import-orig; + tool, with only some rpm-specific functionality added and some + Debian-specific functionality removed. + + + &gbp-import-orig-rpm; imports UPSTREAM-SOURCE + into the &git; repository. UPSTREAM-SOURCE can + either be a gzip, bzip2, lzma or xz compressed tar archive, a zip archive + or an already unpacked source tree. If it is already of the form + package-name-version.tar.gz, the version + information is read from the tarball's filename otherwise it can be given + on the command line via . If the source + package name or version can't be determined &gbp-import-orig-rpm; will + prompt for it unless is given. + + + &gbp-import-orig-rpm; tries to download the archive from a remote server if + a remote URL is given. In addition, if no + UPSTREAM-SOURCE is given &gbp-import-orig-rpm; + takes the archive URI from the spec file - this makes it possible to import + a new upstream version just by bumping the version number in the spec file + and running &gbp-import-orig-rpm; (assuming that the spec file contains + a full URL for the archive and its filename automatically follows the + package version e.g. by using the %{version} macro, of course). + + + The sources are placed on the upstream branch (default: + upstream) and tagged. + + + + OPTIONS + + &man.common.options.description; + + + =VENDOR + + + + Distribution vendor name. + + + + + =VERSION + VERSION + + + The upstream version number. + + + + + + + + Merge the upstream branch to the packaging branch after import. + + + + + =BRANCH-NAME + + + + The branch in the Git repository the upstream sources are put + onto. Default is upstream. + + + + + =BRANCH-NAME + + + + The branch in the Git repository the package is being developed on, + default is master. After importing the new + sources on the upstream branch, &gbp-import-orig-rpm; will try to + merge the new version onto this branch. + + + + + DIRECTORY + + + + Subdirectory that contains the RPM packaging files. + &gbp-import-orig-rpm; uses this to try to find a spec file which, in + turn, is used to get the upstream source archive URI if one is not + specified on the command line. + + + + + + + + + Create missing upstream branch if it does not exist. + + + + + =TAG-NAME + + + + Add TAG-NAME as additional parent to the + commit of the upstream tarball. Useful when upstream uses git and you + want to link to it's revision history. + + + + + + + + + GPG sign all created tags. + + + + + GPG-KEYID + + + + Use this keyid for gpg signing tags. + + + + + TAG-FORMAT + + + + Use this tag format when tagging upstream versions, + default is upstream/%(version)s. + + + + + MSG-FORMAT + + + + Use this format string for the commit message when importing upstream + versions, default is + Imported Upstream version %(version)s. + + + + + PATTERN + + + + Filter out files glob-matching pattern. Can be given multiple times. + + + + + + + + + Generate pristine-tar delta file. + + + + + + + + + If using a filter also filter the files out of the tarball + passed to pristine-tar. + + + + + FILENAME + + + + Filename to record to pristine-tar. This does not alter the tarball + content, just the filename with which the tarball can be checked out + with pristine-tar. + + + + + PREFIX + + + + Prefix (directory) to be used when importing sources into + pristine-tar. Only takes effect when + is used. Special value auto causes &gbp-import-orig-rpm; to guess + the prefix when importing unpacked sources, or, not to change the + prefix when importing source archives. + + + + Using this option will alter the source archive that is imported to + pristine-tar! That is, pristine-tar does not produce and identical + copy of the original tarball (but the mangled tarball, instead). + + + + + + + + + Run CMD after the import. + + + + + + + + Run command interactively, i.e. ask package name and version if + needed. + + + + + + + EXAMPLES + + Download and import a new upstream version using the informantion from the + spec file + + + &gbp-import-orig-rpm; + + + After manually downloading an upstream import it + + + &gbp-import-orig-rpm; ../upstream-tarball-0.1.tar.gz + + + Import unpacked sources + + + &gbp-import-orig-rpm; --orig-prefix=upstream-0.1 ../upstream/ + + + + &man.gbp.config-files; + + + SEE ALSO + + , + , + , + , + &man.seealso.common; + + + + AUTHOR + + &rpm-username; &rpm-email; + + + diff --git a/docs/manpages/gbp-import-srpm.sgml b/docs/manpages/gbp-import-srpm.sgml new file mode 100644 index 0000000..91f6c0a --- /dev/null +++ b/docs/manpages/gbp-import-srpm.sgml @@ -0,0 +1,262 @@ + + +
+ &rpm-email; +
+ + &rpm-firstname; + &rpm-surname; + + + + gbp-import-srpm + &rpm-mansection; + + + git-import-srpm + gbp-import-srpm + Import source RPM packages into a Git repository + + + + &gbp-import-srpm; + &man.common.options.synopsis; + =VENDOR + + + BRANCH-NAME + TAG-FORMAT + + DIRECTORY + + PATTERN + GPG-KEYID + + + + BRANCH-NAME + TAG-FORMAT + + SRPM + + + &gbp-import-srpm; + + + + URL + SRC.RPM + DIRECTORY + + + + + DESCRIPTION + + &gbp-import-srpm; imports an RPM source package into a &git; repository, + notes the package version in the commit logs, and commits the change. All + information, including package name, version and upstream source is + automatically detected from the source package. The tool supports importing + both archived (src.rpm files) or unpacked (directory) source RPMs. + + + + OPTIONS + + &man.common.options.description; + + + =VENDOR + + + + Distribution vendor name. + + + + + =BRANCH-NAME + + + + The branch in the &git; repository the upstream sources are put + onto. Default is upstream. + + + + + =BRANCH-NAME + + + + The branch in the &git; repository the packaging files are put + onto. Default is master. + + + + + + + + + GPG sign all created tags. + + + + + GPG-KEYID + + + + Use this keyid for gpg signing tags. + + + + + TAG-FORMAT + + + + Use this tag format when tagging released versions, + default is %(vendor)s/%(version)s. + + + + + TAG-FORMAT + + + + Use this tag format when tagging upstream versions, + default is upstream/%(version)s. + + + + + DIRECTORY + + + + Subdirectory where to put the RPM packaging files. + + + + + + + + + Import patches to the packaging branch. That is, apply and commit all + patches (that are not marked for manual maintenance) into the + packaging branch after importing other packaging files. The patch + files are automatically removed from the packaging directory and the + spec file if all patches are successufully applied. This option is + ignored if is used. + + + + + PATTERN + + + + Filter out files glob-matching pattern. Can be given multiple times. + + + + + + + + + Generate pristine-tar delta file. + + + + + + + + + Download the source package instead of looking for it in the local + file system. The argument can either be a plain package name or an + URI. The former uses yumdownloader to download the + source while the later uses &wget;. + + + + + + + + + Allow to re-import a package with an already existing version. This + will not re-import the upstream sources - only packaging files will + be re-imported. + + + + + + + + + Use the author identity as the comitter when importing upstream + sources and packaging files. + + + + + + + + + Create missing upstream and/or packaging branch if missing. + + + + + + + + + Import packaging files into an orphan branch that will not be based + on the upstream branch. Useful if you want to maintain (non-native) + package using the 'orphan-packaging' model. This option have no + effect if is used. + + + + + + + + + Treat the package as native package. No separate upstream branch or + upstream tags will be created. + + + + + + + &man.gbp.config-files; + + + SEE ALSO + + + , + , + , + , + &man.seealso.common; + + + + AUTHOR + + &rpm-username; &rpm-email; + + + diff --git a/docs/manpages/gbp-pq-rpm.sgml b/docs/manpages/gbp-pq-rpm.sgml new file mode 100644 index 0000000..3061663 --- /dev/null +++ b/docs/manpages/gbp-pq-rpm.sgml @@ -0,0 +1,399 @@ + + +
+ &rpm-email; +
+ + &rpm-firstname; + &rpm-surname; + + + + gbp-pq-rpm + &rpm-mansection; + + + gbp-pq-rpm + Manage patches and development branches in Git + + + + &gbp-pq-rpm; + &man.common.options.synopsis; + =VENDOR + BRANCH-NAME + BRANCH-NAME + DIRECTORY + FILEPATH + TAG-FORMAT + + FILES + TREEISH + THRESHOLD + REGEX + COMMITISH + + DIRECTORY + + + + + + + + + + + + + DESCRIPTION + + &gbp-pq-rpm; helps in managing patches and development branch(es) for + packages that are maintained with &gbp;. It designed to be used for + packages that are maintained using the "orphan-packaging" model. + &gbp-pq-rpm; has multiple subcommands, or actions, for working with the + branches and patches. + + + &gbp-pq-rpm; makes it easy to do source code development on a separate + development branch (patch-queue branch in Debian git-buildpackage terms). + For example, if the packaging files would be stored in + master the associated development branch would + be development/master. + + + + ACTIONS + + + + + + + Create a development (patch-queue) branch by applying all patches + from the packaging branch on top of the upstream version. The patches + must apply without fuzz. + + + + + + + + + Export patches from the development branch into the packaging branch. + It generates patches (one-per-commit) from the development branch and + updates the spec file accordingly. It doesn't automatically commit + the changes though - they need to verified and committed manually. + + + + + + + + + Switch to the development branch and rebase it against the current + upstream version (indicated in the spec file of the associated + packaging branch). + + + + + + + + + Drop (delete) the development branch associated to the current + branch. For example, you're on branch foo + this would drop branch development/foo. + + + + + + + + + Add a single patch to the development branch - similar to using + git-am. + + + + + + + + + Switch between the development branch and the associated packaging + branch. + + + + + + + + + Convert a package from the "joint-packaging" maintenance model and + git-layout to the "orphan-packaging" model. It takes the content of + the packaging directory, auto-generates patches and puts these into a + new orphan packaging branch. You can use the + to try to preserve as much of the + git history as possible. Converting is a one-time action - conversion + back to the "joint-packaging" model is not supported (yet). + + + + + + + OPTIONS + + &man.common.options.description; + + + =VENDOR + + + + Distribution vendor name. + + + + + =BRANCH-NAME + + + + Branch the packaging files are being maintained on. Only relevant if + a invariable/single development (pq-branch) is defined with + , in which case this is used as the + "base" branch. + + + + + =BRANCH_NAME + + + + Name (format string) of the development (patch-queue) branch. The + following string fields are accepted: "%(branch)s" (the base branch, + i.e. the packaging branch that the development branch is associated + to), "%(upstreamversion)s" (the upstream version), "%(release)s" (the + rpm patchlevel, i.e. Release), "%(version)s" (full rpm package + version). + + + + + DIRECTORY + + + + Subdirectory that contains the RPM packaging files. + + + + + FILEPATH + + + + Relative path to the spec file to use. Special value + auto causes &gbp; to search and guess. + Other values cause the option to be + ignored: the directory of the spec file is used, instead. + + + + + TAG-FORMAT + + + + Use this tag format when looking for tags of upstream versions, + default is upstream/%(version)s. + + + + + + + + Import even if the development (patch-queue) branch already exists. + Only valid for the import action. + + + + + FILES + + + + Comma-separated list of additional file(s) to import from packaging + branch. These will appear as one monolithic patch in the development + (patch-queue) branch. By default, the local gbp conf files are + imported in order to try to ensure that gbp sees the same settings on + the development (pq) branch as on the packaging branch. + + + + + TREEISH + + + + Export patches from TREEISH instead of the + default which is HEAD of the development (patch-queue) branch. + + + + + THRESHOLD + + + + Compress patches larger than given + THRESHOLD bytes. Special value 0 disabled + patch compression. + + + + + REGEX + + + + Exclude changes to path(s) matching REGEX + in patch generation. + + + + + COMMITISH + + + + Squash commits up to the given COMMITISH + into one monolitic diff. Could be used if one wants to squash commits + from an upstream release up to a stable update into a single diff + (commits on top of the stable would generate one patch per commit as + usual). The format is '<commit_ish>[:<filename_base>]', + i.e. commitish optionally followed by a colon and the desired + filename base for the diff (suffix '.diff' is automatically added by + &gbp;). Magic word 'HEAD' translates to the patch-export-treeish when + given as the squash-point. This allows one to configure gbp to + always squash all commits into one monolithic diff. + + + + + + + + + Whether the patch files should start with a number or not. + + + + + DIRECTORY + + + + Directory where packaging files are put in the new orphan packaging + branch after convert. If is not + defined, packaging-dir is used. + + + + + + + + + Try to preserve as much history as possible when converting. That is, + for each commit in the old branch create one corresponding commit in + the new orphan packaging branch. However, commits that will not + generate any changes are skipped (i.e. no empty commits are + generated) - these are caused e.g. by changes in files that are + ignored by patch-generation. + + + + + + + META TAGS + + When exporting patches from a patch-queue branch &gbp-pq-rpm; will look at + the commit message for special tags it recognizes. All tags need to start + at the first column and require at least one whitespace after the colon. + + + + + + + + Ignores the commit, no patch is generated out of it. + + + + + + + + + Conditional patch. Put patch inside "%if <expression>" in the + spec file. + + + + + + + + + Conditional patch. Put patch inside "%ifarch <expression>" in + the spec file. + + + + + + For example, the following commit message: + + + Fix around a problem in Fedora + + which is not applicable elsewhere. + + Gbp-Rpm: If 0%{?fedora} + + + Will result something like this in the spec file: + + + # 0001-Fix-around-a-problem-in-Fedora.patch + %if 0%{?fedora} + %patch0 -p1 + %endif + + + + SEE ALSO + + , + + + + + AUTHOR + + &rpm-username; &rpm-email; + + + diff --git a/docs/manpages/gbp-rpm-ch.sgml b/docs/manpages/gbp-rpm-ch.sgml new file mode 100644 index 0000000..9f6ae99 --- /dev/null +++ b/docs/manpages/gbp-rpm-ch.sgml @@ -0,0 +1,406 @@ + + +
+ &rpm-email; +
+ + &rpm-firstname; + &rpm-surname; + + + + gbp-rpm-ch + &rpm-mansection; + + + git-rpm-ch; + gbp-rpm-ch; + Generate the RPM changelog from git commit messages + + + + &gbp-rpm-ch; + &man.common.options.synopsis; + =VENDOR + BRANCH-NAME + TAG-FORMAT + + DIRECTORY + FILEPATH + FILEPATH + + + MESSAGE + COMMITISH + + + + + NUMBER + REV-FORMAT + GIT-LOG-OPTIONS + + EDITOR + + + + GPG-KEYID + CUSTOMIZATION-FILE + [PATH1 PATH2] + + + + DESCRIPTION + + &gbp-rpm-ch; reads git commit messages up to the current tip of the current + branch and updates the RPM changelog from them. + + + By default, &gbp-rpm-ch; tries to guess the last &git; commit documented in + the changelog. Alternatively, can be used to + tell &gbp-rpm-ch; at which point it should start in the &git; history, or, + to use all commits from the &git; history. + + + The additional path arguments can be used to restrict the repository paths + &gbp-rpm-ch; looks at. For even more detailed control, you can use + to restrict the generated changelog entries + further. E.g. by using + "--author=Foo Bar". + + + + OPTIONS + + &man.common.options.description; + + + =VENDOR + + + + Distribution vendor name. + + + + + =BRANCH-NAME + + + + The branch in the Git repository the package is being developed on, + default is master. + + + + + + + + + Don't check if the current branch matches + PACKAGING-BRANCH. + + + + + TAG-FORMAT + + + + Tag format used, when tagging releases, + default is %(vendor)s/%(version)s + + + + + DIRECTORY + + + + Subdirectory that contains the RPM packaging files. + + + + + FILEPATH + + + + Relative path to the changelog file to use. Special value + auto causes &gbp; to guess, + SPEC uses the spec file, + CHANGES uses a separate changelog file + (name derived spec file name with .spec suffix replaced by .changes). + Guessing logic is simple: use separate changelog file if it is found, + otherwise use the spec file. + + + + + FILEPATH + + + + Relative path to the spec file to use. Special value + auto causes &gbp; to search and guess. + Other values cause the option to be + ignored: the directory of the spec file is used, instead. + + + + + + + + + Use all commits from the Git history, overrides + . + + + + + COMMITTISH + + + + Start reading commit messages at + COMMITTISH. + + + + + + + + + Do not create a new changelog section, just update the last + changelog section. + + + + + + + + + Include the full commit message in the changelog output. + + + + + GIT-LOG-OPTIONS + + + + Options passed on verbatim to git-log(1). + + + + + N + + + + Include N digits of the commit id in the + changelog entry. Default is to not include any commit ids at all. + + + + + REV-FORMAT + + + + Format string to use for revision field in the changelog header. The + following string fields are accepted: + %(upstreamversion)s the upstream version; + %(release)s the rpm patchlevel, i.e. + Release; %(version)s full rpm package + version; %(tagname)s tag/commit, i.e. + basically what git-describe would give. + If empty or not defined the default from packaging policy is used. + + + + + REGEX + + + + Ignore commit lines matching REGEX + when generating the changelog. + + + + + + + + + Use user.name and user.email from + git-config(1) for the changelog header. + + + + + + + + + Whether to spawn an editor: always, when doing a release or never. + + + + + + + + + The editor to use for editing the changelog. + + + + + + + + + Text to use for new changelog entries. Git history and the commit + messages, including and + options are ignored in this case. + + + + + + + + + Commit the changes and create a packaging (release) tag. All + changelog modifications (and importantly, all other staged changes) + are committed to git before creating the tag. This option makes it + possible to create a release and correctly document the the tag name + in the rpm changelog (by using %(tagname)s in the + string). + + + + + + + + + Don't fail tag operations if a tag with the same version already + exists, but, overwrite the existing tag, instead. + + + + + + + + + GPG sign all created tags. + + + + + GPG-KEYID + + + + Use this keyid for gpg signing tags. + + + + + CUSTOMIZATION-FILE + + + + Load Python code from CUSTOMIZATION-FILE. + At the moment, the only useful thing the code can do is define a + custom ChangelogEntryFormatter class. + + + + + + + META TAGS + + Additional to the above options the formatting of the new changelog entries + (one-per-commit) in the changelog can be modified by special tags (called + Meta Tags) given in the git commit message. The tags must start at the + first column of a commit message but can appear on any line. They are of + the form : VALUE. Valid + Meta Tags are: + + + + : ACTION + + + + Supported actions are: Ignore which will + ignore this commit when generating new changelog entries. + Short which will only use the description + (the first line) of the commit message when generating the changelog + entry (useful when is given) and + Full which will use the full commit + message when generating the changelog entry (useful when + is not given). + + + + + : BUGNUMBER + + + + Indicate in the changelog that the bug was addressed by this commit. + + + + + + The following git commit message: + + + Document meta tags + + so one doesn't have to consult the manual + + Git-Rpm-Ch: Short + Closes: #636088 + + + Results in this changelog entry: + + + - Document meta tags (Closes: #636088) + + + + &man.gbp.config-files; + + + SEE ALSO + + , + , + , + , + &man.seealso.common; + + Cl2vcs, + + + + AUTHOR + + &rpm-username; &rpm-email; + + + diff --git a/docs/manpages/man.seealso-rpm.sgml b/docs/manpages/man.seealso-rpm.sgml new file mode 100644 index 0000000..a146875 --- /dev/null +++ b/docs/manpages/man.seealso-rpm.sgml @@ -0,0 +1,12 @@ + + rpmbuild + 1 + , + + git + 1 + , + + pristine-tar + 1 + , diff --git a/docs/manpages/manpages-rpm.ent b/docs/manpages/manpages-rpm.ent new file mode 100644 index 0000000..0839a3b --- /dev/null +++ b/docs/manpages/manpages-rpm.ent @@ -0,0 +1,10 @@ + + + + + + + + + +%COMMON.OPTIONS; diff --git a/docs/manual-rpm.sgml b/docs/manual-rpm.sgml index 2e58730..1de37ff 100644 --- a/docs/manual-rpm.sgml +++ b/docs/manual-rpm.sgml @@ -10,6 +10,14 @@ &ch.development-rpm; &ch.building-rpm; + + Command Reference + &man.gbp.buildpackage.rpm; + &man.gbp.import.orig.rpm; + &man.gbp.import.srpm; + &man.gbp.pq.rpm; + &man.gbp.rpm.ch; + Copyright &gbp.copyright; diff --git a/packaging/git-buildpackage.spec b/packaging/git-buildpackage.spec index e15fc0f..40f4ab8 100644 --- a/packaging/git-buildpackage.spec +++ b/packaging/git-buildpackage.spec @@ -241,6 +241,13 @@ done %{_bindir}/*rpm* %{python_sitelib}/gbp/scripts/*rpm*.py* %{python_sitelib}/gbp/rpm/*py* +%if %{with docs} +%{_mandir}/man1/gbp-buildpackage-rpm.1* +%{_mandir}/man1/gbp-import-orig-rpm.1* +%{_mandir}/man1/gbp-import-srpm.1* +%{_mandir}/man1/gbp-pq-rpm.1* +%{_mandir}/man1/gbp-rpm-ch.1* +%endif %if %{with docs} -- 2.7.4