NAME

       git-debimport - create a git repository from a set of existing Debian packages

SYNOPSIS

       git-debimport [options] path-prefix

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).

OPTIONS

       The following options are available:

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

       --late-merge
              Early versions of git-debimport 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 git-debimport 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.

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

EXAMPLE

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

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

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:

       upstream - for the pristine upstream source
       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 debsnap(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.

BUGS

       git-debimport 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.

SEE ALSO

       gitpkg(1), debsnap(1)

AUTHOR

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

                                        September 21, 2007                       GIT-DEBIMPORT(1)