title	section	header	footer	author	date	adjusting	hyphenate
git-deb-pkg	1	User manual	git-deb-pkg	Sébastien Gross	2016-02-09 06:37:24 -0800	b	true

NAME

git-deb-pkg - lazy way to build Debian package using git

SYNOPSIS

git deb-pkg [ options ] [ commands ]

DESCRIPTION

git deb-pkg offers a simple and easy way to manage Debian package generation using git (and other source code management system).

Both upstream and Debian code are kept in separated branches.

Features:

• Update upstream from any SCM which git is capable of.
• Checkout any file from any branch.
• Cherry pick any commit.
• Few files to edit.
• Keep ./debian in a specific git branch.

OPTIONS

General options

-t DIR|--templates-dir DIR : Directory where the debhelper files reside (default: /usr/share/git-deb-pkg/templates).

-h|--help : Shows help screen.

git options

-u BRANCH|--upstream-branch BRANCH : Upstream branch (default: upstream).

-d BRANCH|--debian-branch BRANCH : Debian branch (default: debian).

-U|--no-upstream-update : Do not update upstream branch.

-C|--no-changelog-update : Do not update debian changelog.

COMMANDS

init-debian : Init debian directory.

set-defaults : Sets default options to git configuration.

commit-debian : Commit the debian directory.

build : Build debian package.

source : Build debian source package only.

show-version : Show all versions for the package.

update-upstream : Update upstream branch.

prepare : Prepare building environment.

prepare-orig : Prepare upstream orig archive.

CONFIGURATION OPTIONS

git-deb-pkg stores variables in git repository options.

Variables

deb-pkg.scm : Specify the source code management system to use. Default: git.

deb-pkg.upstream : Specify the branch to use as upstream code. Default: upstream.

deb-pkg.debian : Specify the branch to use for debian package definition. Default: debian.

deb-pkg.revision-scheme : Regexp to extract version number from git describe. The git patchlevel -PL-gTREEISH is cut off before the regexp is applied. Default: s/^v-(.*)$/\1/;s/[-]/./g. See UNDERSTANDING REVISION SCHEME.

deb-pkg.cherrypick : Special commits to cherry pick. This option can occur many times. Order matters. Default: none.

deb-pkg.checkout : Extra branch, directories or files to checkout before building the package. This option can occur many times. Order matters. The syntax of each item is: branch[:directory or file]. Default: none.

HOW TO USE

Clone remote directory

First of all the upstream repository should be cloned the repository from a remote source. Depending on the remote used SCM the commands may differ.

git

mkdir git-project
cd git-project
git remote add upstream git://remote.host/path/to/repository
git fetch --all
git checkout -b upstream upstream/master
git checkout master

svn

mkdir git-project
cd git-project
git svn -i upstream clone clone http://remote.host/path/to/repository .

cvs

git cvsimport -d:pserver:anonymous@remote.host/path/to/repository \
    -r master -o master -a -C . -v module

Create the ./debian directory

This is where the magic starts. git deb-pkg helps a lot for that part:

git deb-pkg set-defaults
git deb-pkg init-debian

Package could be built using debuild command:

debuild --no-tgz-check -I.git -i'\.git/'

To cancel and return to previous branch (assuming it was master) just run:

debuild clean \
	&& git reset --hard \
	&& git checkout master \
	&& git branch -D debian-dev

Then a few files in the ./debian directory have to be updated, and commited:

debuild clean
git deb-pkg commit-debian

build the package

To build the package from any branch, just type:

git deb-pkg build

build the source package

To build the source package from any branch, just type:

git deb-pkg source

publish package

This step is not mandatory unless you wish to publish your work:

git remote add origin user@git.example.com:/path/to/repository.git
git push -u origin master

keep package up to date

git

git checkout master
git fetch -a
git merge upstream

svn

git checkout master
git svn fetch
git merge upstream

UNDERSTANDING REVISION SCHEME

For example if the git tag is v-1.2 and 5 commits before the upstream branch, git describe would produce something like:

v-1.2-5-gddf4ca0

Where:

• v-1.2 is the current tag (understand upstram version)
• 5 is the number of commits after the current tag. This is the patch level (PL)
• ddf5ca0 is the current commit ID prefixed with g. This is the git TREEISH.

The regexp defined in deb-pkg.revision-scheme variable is applied to the current tag (v-1.2) and extracts the upstream version ('1.2').

The Debian package version would thus be: 1:1.2*git.5-1 which means:

• version 1.2 of the upstream
• git patch level 5
• debian package revision 1

See the Debian policy manual, controle files and their fields, Version (http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version)

SEE ALSO

git(1), debhelper(7).

HISTORY

2016/02/09 : Update template directory

2016/01/11 : create debian patch when modifing autoconf.ac

2012/01/10 : Add set-defaults option.

2011/12/09 : Fix DpkgVersion invocation.

2011/09/19 : Add source command.

2011/03/23 : Use git configuration file for options.

2011/03/22 : Change name from debian-builder to git-deb-pkg to git git tool suite.

2010/09/23 : Initial release.

BUGS

No time to include bugs, command actions might seldom lead astray user's assumption.

COPYRIGHT

Copyright © 2010-2016 Sébastien Gross <seb•ɑƬ•chezwam•ɖɵʈ•org>.

Relesed under WTFPL (http://sam.zoy.org/wtfpl/COPYING).