git-deb-pkg.1

.\" Automatically generated by Pandoc 1.15.2.1
.\"
.ad b
.hy
.TH "git\-deb\-pkg" "1" "2016\-02\-09 14:37:24" "git\-deb\-pkg" "User manual"
.SH NAME
.PP
git\-deb\-pkg \- lazy way to build Debian package using git
.SH SYNOPSIS
.PP
git deb\-pkg [ \f[I]options\f[] ] [ commands ]
.SH DESCRIPTION
.PP
\f[I]git deb\-pkg\f[] offers a simple and easy way to manage Debian
package generation using git (and other source code management system).
.PP
Both upstream and Debian code are kept in separated branches.
.PP
Features:
.IP \[bu] 2
Update upstream from any SCM which git is capable of.
.IP \[bu] 2
Checkout any file from any branch.
.IP \[bu] 2
Cherry pick any commit.
.IP \[bu] 2
Few files to edit.
.IP \[bu] 2
Keep \f[B]\&./debian\f[] in a specific git branch.
.SH OPTIONS
.SS General options
.TP
.B \-t DIR|\-\-templates\-dir DIR
Directory where the \f[I]debhelper\f[] files reside (default:
\f[B]/usr/share/git\-deb\-pkg/templates\f[]).
.RS
.RE
.TP
.B \-h|\-\-help
Shows help screen.
.RS
.RE
.SS git options
.TP
.B \-u BRANCH|\-\-upstream\-branch BRANCH
Upstream branch (default: \f[B]upstream\f[]).
.RS
.RE
.TP
.B \-d BRANCH|\-\-debian\-branch BRANCH
Debian branch (default: \f[B]debian\f[]).
.RS
.RE
.TP
.B \-U|\-\-no\-upstream\-update
Do not update upstream branch.
.RS
.RE
.TP
.B \-C|\-\-no\-changelog\-update
Do not update debian changelog.
.RS
.RE
.SH COMMANDS
.TP
.B init\-debian
Init debian directory.
.RS
.RE
.TP
.B set\-defaults
Sets default options to git configuration.
.RS
.RE
.TP
.B commit\-debian
Commit the debian directory.
.RS
.RE
.TP
.B build
Build debian package.
.RS
.RE
.TP
.B source
Build debian source package only.
.RS
.RE
.TP
.B show\-version
Show all versions for the package.
.RS
.RE
.TP
.B update\-upstream
Update upstream branch.
.RS
.RE
.TP
.B prepare
Prepare building environment.
.RS
.RE
.TP
.B prepare\-orig
Prepare upstream orig archive.
.RS
.RE
.SH CONFIGURATION OPTIONS
.PP
\f[I]git\-deb\-pkg\f[] stores variables in git repository options.
.SS Variables
.TP
.B deb\-pkg.scm
Specify the source code management system to use.
Default: \f[B]git\f[].
.RS
.RE
.TP
.B deb\-pkg.upstream
Specify the branch to use as upstream code.
Default: \f[B]upstream\f[].
.RS
.RE
.TP
.B deb\-pkg.debian
Specify the branch to use for debian package definition.
Default: \f[B]debian\f[].
.RS
.RE
.TP
.B deb\-pkg.revision\-scheme
Regexp to extract version number from \f[I]git describe\f[].
The git patchlevel \f[I]\-PL\-gTREEISH\f[] is cut off before the regexp
is applied.
Default: \f[B]s/^v\-(.*)$//;s/[\-]/./g\f[].
See UNDERSTANDING REVISION SCHEME.
.RS
.RE
.TP
.B deb\-pkg.cherrypick
Special commits to cherry pick.
This option can occur many times.
Order matters.
Default: none.
.RS
.RE
.TP
.B 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: \f[I]branch[:directory or file]\f[].
Default: none.
.RS
.RE
.SH HOW TO USE
.SS Clone remote directory
.PP
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.
.SS git
.IP
.nf
\f[C]
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
\f[]
.fi
.SS svn
.IP
.nf
\f[C]
mkdir\ git\-project
cd\ git\-project
git\ svn\ \-i\ upstream\ clone\ clone\ http://remote.host/path/to/repository\ .
\f[]
.fi
.SS cvs
.IP
.nf
\f[C]
git\ cvsimport\ \-d:pserver:anonymous\@remote.host/path/to/repository\ \\
\ \ \ \ \-r\ master\ \-o\ master\ \-a\ \-C\ .\ \-v\ module
\f[]
.fi
.SS Create the \f[B]\&./debian\f[] directory
.PP
This is where the magic starts.
\f[I]git deb\-pkg\f[] helps a lot for that part:
.IP
.nf
\f[C]
git\ deb\-pkg\ set\-defaults
git\ deb\-pkg\ init\-debian
\f[]
.fi
.PP
Package could be built using \f[I]debuild\f[] command:
.IP
.nf
\f[C]
debuild\ \-\-no\-tgz\-check\ \-I.git\ \-i\[aq]\\.git/\[aq]
\f[]
.fi
.PP
To cancel and return to previous branch (assuming it was
\f[B]master\f[]) just run:
.IP
.nf
\f[C]
debuild\ clean\ \\
\ \ \ \ &&\ git\ reset\ \-\-hard\ \\
\ \ \ \ &&\ git\ checkout\ master\ \\
\ \ \ \ &&\ git\ branch\ \-D\ debian\-dev
\f[]
.fi
.PP
Then a few files in the \f[I]\&./debian\f[] directory have to be
updated, and commited:
.IP
.nf
\f[C]
debuild\ clean
git\ deb\-pkg\ commit\-debian
\f[]
.fi
.SS build the package
.PP
To build the package from any branch, just type:
.IP
.nf
\f[C]
git\ deb\-pkg\ build
\f[]
.fi
.SS build the source package
.PP
To build the source package from any branch, just type:
.IP
.nf
\f[C]
git\ deb\-pkg\ source
\f[]
.fi
.SS publish package
.PP
This step is not mandatory unless you wish to publish your work:
.IP
.nf
\f[C]
git\ remote\ add\ origin\ user\@git.example.com:/path/to/repository.git
git\ push\ \-u\ origin\ master
\f[]
.fi
.SS keep package up to date
.SS git
.IP
.nf
\f[C]
git\ checkout\ master
git\ fetch\ \-a
git\ merge\ upstream
\f[]
.fi
.SS svn
.IP
.nf
\f[C]
git\ checkout\ master
git\ svn\ fetch
git\ merge\ upstream
\f[]
.fi
.SH UNDERSTANDING REVISION SCHEME
.PP
For example if the git tag is \f[B]v\-1.2\f[] and 5 commits before the
\f[B]upstream\f[] branch, \f[I]git describe\f[] would produce something
like:
.IP
.nf
\f[C]
v\-1.2\-5\-gddf4ca0
\f[]
.fi
.PP
Where:
.IP \[bu] 2
\f[B]v\-1.2\f[] is the current tag (understand upstram version)
.IP \[bu] 2
\f[B]5\f[] is the number of commits after the current tag.
This is the patch level (\f[I]PL\f[])
.IP \[bu] 2
\f[B]ddf5ca0\f[] is the current commit ID prefixed with \f[I]g\f[].
This is the git \f[I]TREEISH\f[].
.PP
The regexp defined in \f[B]deb\-pkg.revision\-scheme\f[] variable is
applied to the current tag (\f[B]v\-1.2\f[]) and extracts the upstream
version (\[aq]1.2\[aq]).
.PP
The Debian package version would thus be: **1:1.2*git.5\-1** which
means:
.IP \[bu] 2
version \f[I]1.2\f[] of the upstream
.IP \[bu] 2
git patch level \f[I]5\f[]
.IP \[bu] 2
debian package revision \f[I]1\f[]
.PP
See the Debian policy manual, controle files and their fields, Version
(http://www.debian.org/doc/debian\-policy/ch\-controlfields.html#s\-f\-Version)
.SH SEE ALSO
.PP
git(1), debhelper(7).
.SH HISTORY
.TP
.B 2016/02/09
Update template directory
.RS
.RE
.TP
.B 2016/01/11
create debian patch when modifing \f[I]autoconf.ac\f[]
.RS
.RE
.TP
.B 2012/01/10
Add set\-defaults option.
.RS
.RE
.TP
.B 2011/12/09
Fix DpkgVersion invocation.
.RS
.RE
.TP
.B 2011/09/19
Add source command.
.RS
.RE
.TP
.B 2011/03/23
Use git configuration file for options.
.RS
.RE
.TP
.B 2011/03/22
Change name from \f[I]debian\-builder\f[] to \f[I]git\-deb\-pkg\f[] to
git git tool suite.
.RS
.RE
.TP
.B 2010/09/23
Initial release.
.RS
.RE
.SH BUGS
.PP
No time to include bugs, command actions might seldom lead astray
user\[aq]s assumption.
.SH COPYRIGHT
.PP
Copyright © 2010\-2016 Sébastien Gross <seb•ɑƬ•chezwam•ɖɵʈ•org>.
.PP
Relesed under WTFPL (http://sam.zoy.org/wtfpl/COPYING).
.SH AUTHORS
Sébastien Gross.