.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH GIT\-DEBIMPORT 1 "September 21, 2007"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
git\-debimport \- create a git repository from a set of existing Debian packages
.SH SYNOPSIS
.B git\-debimport
.RI [ options ] " path\-prefix"

.SH DESCRIPTION
This program will create a git repository of all files that match
${path\-prefix}_*.diff.gz or ${path\-prefix}_*.debian.tar.{gz,bz2,xz} (with their
corresponding orig.tar.{gz,bz2,xz}), or of all files that match
${path\-prefix}_*.tar.{gz,bz2,xz} (for Debian native packages).


.SH OPTIONS
The following options are available:

.TP
.B \-\-fetch
Attempt to download all available versions from snapshot.debian.org rather
than use an existing set of packages.  The \fBdebsnap\fP(1) utility, from
devscripts 2.10.63 or later, must be available in the path to use this option
(earlier \fBdebsnap\fP versions only supported snapshot.debian.net which is no
longer a functional mirror).  The packages will be downloaded into the location
implied by the \fIpath\-prefix\fP where they would normally be expected to exist
already without this option.  Downloaded packages will not automatically be
removed after this operation is complete.

.TP
.B \-\-late\-merge
Early versions of \fBgit\-debimport\fP would only merge the upstream and debian
branches after the import of all packages was complete.  This avoids an import
failing where the merge might have conflicts that would need to be manually
resolved.  We know the import of the next package in the series will contain a
resolution to any such conflict, so delaying the merge allows the import to
proceed without intervention or introducing changes that were not part of the
original history.  It does however produce a lesser quality history for the
purposes of browsing the Debian changes.  All the original packages may be
retrieved from such a repo with perfect fidelity, but the diff between adjacent
Debian versions will be mingled with upstream changes too.

The default for current versions of \fBgit\-debimport\fP is to merge each new
upstream release as it is imported.  This gives a much more natural and useful
looking history, but may fail in some cases.  Use this option to employ the
older more reliable method for packages that generate conflicts during import.

.TP
.B \-v, \-\-verbose
Be more noisy about reporting operations in progress.  Mostly only useful with
the \fB\-\-fetch\fP option at present.


.SH EXAMPLE
Import an archive of existing 'mypackagename' packages from mysrcdir:
.br
$ mkdir mydestdir && cd mydestdir
.br
$ git\-debimport ../mysrcdir/mypackagename

Import all available versions of \fBgitpkg\fP from snapshot.debian.org:
.br
$ mkdir mydestdir && cd mydestdir
.br
$ git\-debimport \-\-fetch ../my\-gitpkg\-sources/gitpkg


.SH NOTES
It is unfortunate that at the present time, many of the tools for importing
source to git from an existing revision control system all leave something to
be desired.  This script does not solve that problem.  What it does do however
is create a repository that makes it possible to accurately extract all of the
earlier packages which were injected to it.  This is sadly more than can be said
for the result of running git\-cvsimport on a repo created by cvs\-buildpackage,
for example.

It is currently very simple, and makes a number of hard-coded assumptions about
the resulting repo.  For debian-versioned packages it will create a repo with
two branches:

.BR upstream " \- for the pristine upstream source"
.br
.BR master " \- for the Debianised source"

Native versioned packages will have only the master branch.

While the loss of fine grained history on individual commits is most
regrettable, this script enables a maintainer to import a usable record of
the previously released packages as a base for future development.  This may
be an acceptable trade-off for people who feel the advantage of moving future
development to git now outweighs the inconvenience of needing to refer to a
legacy repository for full details of previous commits.

Hopefully the problems of accurately importing from other revision control
systems will be solved one day, but in the meantime, a brief but accurate
history seems more useful than a detailed but largely bogus one.

With the addition of the \fBdebsnap\fP(1) tool, the useful life of this has been
extended beyond the originally envisaged need.  People who do not have access to
the original revision control history at all can build for themselves a useful
base for further development, quickly and easily, from the packages that are
still available on public snapshot mirrors.


.SH BUGS
\fBgit\-debimport\fP does not currently handle packages with mixed 'native' and
debian-versioned releases.  This may be added in a later version if people have
real examples of such packages they wish to import with it and we figure out a
sensible convention for how they should be stored in the resulting repository.

Nothing particularly intelligent is done with format 3.0 (quilt) patches currently.
The debian/patches, if any, are simply imported verbatim as found in the source
package.  Ideally they should be committed to some git branch and generated on
demand at export time, rather than perpetuating the patch-in-patch nightmare.
Any packages so imported will be recreated accurately on export, but this isn't
really the best form to actually work with them in git in most cases.

.SH SEE ALSO
.BR gitpkg (1),
.BR debsnap (1)

.SH AUTHOR
gitpkg was written by Ron <ron@debian.org>.