dgit-user

dgit-user(7)                         dgit                         dgit-user(7)



NAME
       dgit-user - making and sharing changes to Debian packages, with git

INTRODUCTION
       dgit lets you fetch the source code to every package on your system as
       if your distro used git to maintain all of it.

       You can then edit it, build updated binary packages (.debs) and install
       and run them.  You can also share your work with others.

       This tutorial gives some recipes and hints for this.  It assumes you
       have basic familiarity with git.  It does not assume any initial
       familiarity with Debian's packaging processes.

       If you are a package maintainer within Debian; a DM or DD; and/or a
       sponsee: this tutorial is not for you.  Try dgit-nmu-simple(7),
       dgit-maint-*(7), or dgit(1) and dgit(7).

SUMMARY
       (These runes will be discussed later.)

           % dgit clone glibc jessie,-security
           % cd glibc
           % curl 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
           % git commit -a -m 'Fix libc lost output bug'
           % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
           % mk-build-deps --root-cmd=sudo --install
           % dpkg-buildpackage -uc -b
           % sudo dpkg -i ../libc6_*.deb

       Occasionally:

           % git clean -xdf
           % git reset --hard

       Later:

           % cd glibc
           % dgit pull jessie,-security
           % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit
           % dpkg-buildpackage -uc -b
           % sudo dpkg -i ../libc6_*.deb

FINDING THE RIGHT SOURCE CODE - DGIT CLONE
           % dgit clone glibc jessie,-security
           % cd glibc

       dgit clone needs to be told the source package name (which might be
       different to the binary package name, which was the name you passed to
       "apt-get install") and the codename or alias of the Debian release
       (this is called the "suite").

   Finding the source package name
       For many packages, the source package name is obvious.  Otherwise, if
       you know a file that's in the package, you can look it up with dpkg:

           % dpkg -S /lib/i386-linux-gnu/libc.so.6
           libc6:i386: /lib/i386-linux-gnu/libc.so.6
           % dpkg -s libc6:i386
           Package: libc6
           Status: install ok installed
           ...
           Source: glibc

       (In this example, libc6 is a "multi-arch: allowed" package, which means
       that it exists in several different builds for different architectures.
       That's where ":i386" comes from.)

   Finding the Debian release (the "suite")
       Internally, Debian (and derived) distros normally refer to their
       releases by codenames.  Debian also has aliases which refer to the
       current stable release etc.  So for example, at the time of writing
       Debian "jessie" (Debian 8) is Debian "stable"; and the current version
       of Ubuntu is "yakkety" (Yakkety Yak, 16.10).  You can specify either
       the codename "jessie" or the alias "stable".  If you don't say, you get
       "sid", which is Debian "unstable" - the main work-in progress branch.

       If you don't know what you're running, try this:

           % grep '^deb' /etc/apt/sources.list
           deb http://the.earth.li/debian/ jessie main non-free contrib
           ...
           %

       For Debian, you should add ",-security" to the end of the suite name,
       unless you're on unstable or testing.  Hence, in our example "jessie"
       becomes "jessie,-security".  (Yes, with a comma.)

WHAT DGIT CLONE PRODUCES
   What branches are there
       dgit clone will give you a new working tree, and arrange for you to be
       on a branch named like "dgit/jessie,-security" (yes, with a comma in
       the branch name).

       For each release (like "jessie") there is a tracking branch for the
       contents of the archive, called "remotes/dgit/dgit/jessie" (and
       similarly for other suites).  This can be updated with "dgit fetch
       jessie".  This, the remote suite branch, is synthesized by your local
       copy of dgit.  It is fast forwarding.

       Debian separates out the security updates, into "*-security".  Telling
       dgit "jessie,-security" means that it should include any updates
       available in "jessie-security".  The comma notation is a request to
       dgit to track jessie, or jessie-security if there is an update for the
       package there.

       (You can also dgit fetch in a tree that wasn't made by dgit clone.  If
       there's no "debian/changelog" you'll have to supply a "-p"package
       option to dgit fetch.)

   What kind of source tree do you get
       If the Debian package is based on some upstream release, the code
       layout should be like the upstream version.  You should find "git grep"
       helpful to find where to edit.

       The package's Debian metadata and the scripts for building binary
       packages are under "debian/".  "debian/control", "debian/changelog" and
       "debian/rules" are the starting points.  The Debian Policy Manual has
       most of the in-depth technical details.

       For many Debian packages, there will also be some things in
       "debian/patches/".  It is best to ignore these.  Insofar as they are
       relevant the changes there will have been applied to the actual files,
       probably by means of actual comments in the git history.  The contents
       of debian/patches are ignored when building binaries from dgitish git
       branches.

       (For Debian afficionados: the git trees that come out of dgit are
       "patches-applied packaging branches without a .pc directory".)

   What kind of history you get
       If you're lucky, the history will be a version of, or based on, the
       Debian maintainer's own git history, or upstream's git history.

       But for many packages the real git history does not exist, or has not
       been published in a dgitish form.  So you may find that the history is
       a rather short history invented by dgit.

       dgit histories often contain automatically-generated commits, including
       commits which make no changes but just serve to make a rebasing branch
       fast-forward.  This is particularly true of combining branches like
       "jessie,-security".

       If the package maintainer is using git then after dgit clone you may
       find that there is a useful "vcs-git" remote referring to the Debian
       package maintainer's repository for the package.  You can see what's
       there with "git fetch vcs-git".  But use what you find there with care:
       Debian maintainers' git repositories often have contents which are very
       confusing and idiosyncratic.  In particular, you may need to manually
       apply the patches that are in debian/patches before you do anything
       else!

BUILDING
   Always commit before building
           % wget 'https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=28250;mbox=yes;msg=89' | patch -p1 -u
           % git commit -a -m 'Fix libc lost output bug'

       Debian package builds are often quite messy: they may modify files
       which are also committed to git, or leave outputs and temporary files
       not covered by ".gitignore".

       If you always commit, you can use

           % git clean -xdf
           % git reset --hard

       to tidy up after a build.  (If you forgot to commit, don't use those
       commands; instead, you may find that you can use "git add -p" to help
       commit what you actually wanted to keep.)

       These are destructive commands which delete all new files (so you must
       remember to say "git add") and throw away edits to every file (so you
       must remember to commit).

   Update the changelog (at least once) before building
           % gbp dch -S --since=dgit/dgit/sid --ignore-branch --commit

       The binaries you build will have a version number which ultimately
       comes from the "debian/changelog".  You want to be able to tell your
       binaries apart from your distro's.

       So you should update "debian/changelog" to add a new stanza at the top,
       for your build.

       This rune provides an easy way to do this.  It adds a new changelog
       entry with an uninformative message and a plausible version number
       (containing a bit of your git commit id).

       If you want to be more sophisticated, the package "dpkg-dev-el" has a
       good Emacs mode for editing changelogs.  Alternatively, you could edit
       the changelog with another text editor, or run "dch" or "gbp dch" with
       different options.  Choosing a good version number is slightly tricky
       and a complete treatment is beyond the scope of this tutorial.

   Actually building
           % mk-build-deps --root-cmd=sudo --install
           % dpkg-buildpackage -uc -b

       dpkg-buildpackage is the primary tool for building a Debian source
       package.  "-uc" means not to pgp-sign the results.  "-b" means build
       all binary packages, but not to build a source package.

   Using sbuild
       You can build in an schroot chroot, with sbuild, instead of in your
       main environment.  (sbuild is used by the Debian build daemons.)

           % git clean -xdf
           % sbuild -c jessie -A --no-clean-source \
                    --dpkg-source-opts='-Zgzip -z1 --format=1.0 -sn'

       Note that this will seem to leave a "source package" (.dsc and .tar.gz)
       in the parent directory, but that source package should not be used.
       It is likely to be broken.  For more information see Debian bug
       #868527.

INSTALLING
   Debian Jessie or older
           % sudo dpkg -i ../libc6_*.deb

       You can use "dpkg -i" to install the .debs that came out of your
       package.

       If the dependencies aren't installed, you will get an error, which can
       usually be fixed with "apt-get -f install".

   Debian Stretch or newer
           % sudo apt install ../libc6_*.deb

Multiarch
       If you're working on a library package and your system has multiple
       architectures enabled, you may see something like this:

           dpkg: error processing package libpcre3-dev:amd64 (--configure):
            package libpcre3-dev:amd64 2:8.39-3~3.gbp8f25f5 cannot be configured because libpcre3-dev:i386 is at a different version (2:8.39-2)

       The multiarch system used by Debian requires each package which is
       present for multiple architectures to be exactly the same across all
       the architectures for which it is installed.

       The proper solution is to build the package for all the architectures
       you have enabled.  You'll need a chroot for each of the secondary
       architectures.  This is somewhat tiresome, even though Debian has
       excellent tools for managing chroots.  "sbuild-debian-developer-setup"
       from the package of the same name and "sbuild-createchroot" from the
       "sbuild" package are good starting points.

       Otherwise you could deinstall the packages of interest for those other
       architectures with something like "dpkg --remove libpcre3:i386".

       If neither of those are an option, your desperate last resort is to try
       using the same version number as the official package for your own
       package.  (The version is controlled by "debian/changelog" - see
       above.)  This is not ideal because it makes it hard to tell what is
       installed, and because it will mislead and confuse apt.

       With the "same number" approach you may still get errors like

           trying to overwrite shared '/usr/include/pcreposix.h', which is
           different from other instances of package libpcre3-dev

       but passing "--force-overwrite" to dpkg will help - assuming you know
       what you're doing.

SHARING YOUR WORK
       The "dgit/jessie,-security" branch (or whatever) is a normal git
       branch.  You can use "git push" to publish it on any suitable git
       server.

       Anyone who gets that git branch from you will be able to build binary
       packages (.deb) just as you did.

       If you want to contribute your changes back to Debian, you should
       probably send them as attachments to an email to the Debian Bug System
       <https://bugs.debian.org/> (either a followup to an existing bug, or a
       new bug).  Patches in "git-format-patch" format are usually very
       welcome.

   Source packages
       The git branch is not sufficient to build a source package the way
       Debian does.  Source packages are somewhat awkward to work with.
       Indeed many plausible git histories or git trees cannot be converted
       into a suitable source package.  So I recommend you share your git
       branch instead.

       If a git branch is not enough, and you need to provide a source package
       but don't care about its format/layout (for example because some
       software you have consumes source packages, not git histories) you can
       use this recipe to generate a "3.0 (native)" source package, which is
       just a tarball with accompanying .dsc metadata file:

           % echo '3.0 (native)' >debian/source/format
           % git commit -m 'switch to native source format' debian/source/format
           % dgit -wgf build-source

       If you need to provide a good-looking source package, be prepared for a
       lot more work.  You will need to read much more, perhaps starting with
       dgit-nmu-simple(7), dgit-sponsorship(7) or dgit-maint-*(7)

SEE ALSO
       dgit(1), dgit(7)



perl v5.28.2                    Debian Project                    dgit-user(7)