These are tools that help preparing/operating/modifying patches and
.spec files during the tough life of packagers.
So you are a package maintainer. As a first step, you use the whole OBS because you do not want to live in a stone age clinging rocks to get a fire. But as a next step, you aren't happy to use Quilt from back to 2003 (a bronze age, to be fair), so you want to be modern and keep all your patches in the Git repository, instead of directly inside your package.
But you quickly discover that Git has some limitations, which are preventing you from getting it right. Limitations are these:
-
Naturally, Git creates patches with an order number:
NNNN_commit_name.patch, so you know the order which patch after which. But theNNNNthing generates all the problems for you. -
After you renamed patches, you now need to keep track of their order inside your
.specfile. It might work with 10-20 patches, but you will get lost if they are exceeding 20 and you need to "shuffle" them around, shifting their order during version update etc. -
In package terms, a commit to a Git is not always a patch. A patch may contain (and usually does) several commits. So every time you squash few commits into one patch and then rebase the whole thing, you usually do
force-push. This is perfectly OK for tracking the patches in a dedicated Git repo. Howeverforce-pushrenders commit ID changing, while an actual code mostly do not change. The package changelog and its history, however, reflects this change, because it is a valid diff. So your package reviewer might see countless "changes" that aren't as such.
The git-format-pkg-patch tool is here to:
- Format patches from a specific range of commits or tags etc.
- Re-format them the way they are compatible with OBS change tracking policies
- Replace/update existing patches if necessary
- Generate an inclusion text file for
.changeslog - Use those patches that actually makes sense to be replaced.
You may ask, if we want to avoid the bronze age, why use patches at all? Since instead we could just keep all the patches in Git, and then automatically generate tarballs directly from the head of a Git branch. And in fact there are also tools to help automate that, e.g.
One answer is that sometimes it is desired to take the sources from an official release tag as a tarball with an exact checksum, and then put patches on top of that.
Please read up to date man page.
First, you create your patches somewhere within your Git project foo:
mkdir -p /home/you/foo/patchesgit-format-pkg-patch -f TAG
Where TAG is your release tag (or commits range if you don't use
tagging) in Git against which you are creating your set of patches.
Second (version A), assuming /home/you/foo/patches is accessible, so
you go to your OBS project and update the patches with it:
cd /home/you/obs/projectgit-format-pkg-patch -u /home/you/foo/patches
It will report you what was added/changed/removed and will generate a text file
patches.changes.txt in the same directory, which you can reuse to
include its content into .changes log of the package.
Second (version B), you do the same as above, except add option -c
during the next step like this:
git-format-pkg-patch -u /home/you/foo/patches -c
This will do the same as above, but will actually update the contents of those files.