Provided by: dgit_9.2_all bug

NAME

       dgit - git integration with the Debian archive

SYNOPSIS

       dgit [dgit-opts] clone [dgit-opts] package [suite] [./dir|/dir]
       dgit [dgit-opts] fetch|pull [dgit-opts] [suite]
       dgit [dgit-opts] build|sbuild|build-source [build-opts]
       dgit [dgit-opts] pbuilder|cowbuilder [debbuildopts]
       dgit [dgit-opts] push|push-source [dgit-opts] [suite]
       dgit [dgit-opts] rpush build-host:build-dir [push args...]
       dgit [dgit-opts] action ...

DESCRIPTION

       dgit  allows  you to treat the Debian archive as if it were a git repository.  Conversely,
       it allows Debian to publish the source of its packages as git branches, in a format  which
       is directly useable by ordinary people.

       This is the command line reference.  Please read the tutorial(s):

       dgit-user(7)              for users: edit, build and share packages
       dgit-nmu-simple(7)        for DDs: do a straightforward NMU
       dgit-maint-native(7)      for maintainers of Debian-native packages
       dgit-maint-debrebase(7)   for maintainers: a pure-git rebasish workflow
       dgit-maint-merge(7)       for maintainers: a pure-git merging workflow
       dgit-maint-gbp(7)         for maintainers already using git-buildpackage
       dgit-sponsorship(7)       for sponsors and sponsored contributors
       dgit-downstream-dsc(7)    setting up dgit push for a new distro

       See dgit(7) for detailed information about the data model, common problems likely to arise
       with certain kinds of package, etc.

OPERATIONS

       dgit clone package [suite] [./dir|/dir]
              Consults the archive and dgit-repos to  construct  the  git  view  of  history  for
              package  in suite (sid by default) in a new directory (named ./package by default);
              also, downloads any necessary orig tarballs.

              The suite's git tip is left on the local branch dgit/suite ready for work,  and  on
              the corresponding dgit remote tracking branch.  The origin remote will be set up to
              point to the package's dgit-repos tree for the distro to which suite belongs.

              suite  may  be  a  combination  of  several   underlying   suites   in   the   form
              mainsuite,subsuite...; see COMBINED SUITES in dgit(7).

              For  your convenience, the vcs-git remote will be set up from the package's Vcs-Git
              field, if there is one - but note that in the general case the history found  there
              may  be different to or even disjoint from dgit's view.  (See also dgit update-vcs-
              git.)

       dgit fetch [suite]
              Consults the archive and git-repos to update the git view of history for a specific
              suite  (and downloads any necessary orig tarballs), and updates the remote tracking
              branch remotes/dgit/dgit/suite.  If the current  branch  is  dgit/suite  then  dgit
              fetch  defaults  to  suite; otherwise it parses debian/changelog and uses the suite
              specified there.  suite may be a combined suite, as for clone.

       dgit pull [suite]
              Does dgit fetch, and then merges  the  new  head  of  the  remote  tracking  branch
              remotes/dgit/dgit/suite into the current branch.

       dgit checkout suite
              Checks out the local branch dgit/suite.

              If the branch does not exist, dgit checkout creates it, and sets it up the same way
              as dgit clone would.  In that case, if the archive remote tracking branch does  not
              exist, dgit checkout will do a dgit fetch first.

              NB: dgit checkout will only do a fetch if it has to.  If you already have the suite
              branch, and want to merge your branch with updates from the archive, use dgit pull.

              dgit checkout will normally need to access the archive server, to canonicalise  the
              provided  suite  name.  The exception is if you specify the canonical name, and the
              branch (or tracking branch) already exists.

       dgit build ...
              Runs dpkg-buildpackage with some suitable options.   Options  and  arguments  after
              build  will  be  passed  on  to dpkg-buildpackage.  It is not necessary to use dgit
              build when using dgit; it is  OK  to  use  any  approach  which  ensures  that  the
              generated source package corresponds to the relevant git commit.

              Tagging, signing and actually uploading should be left to dgit push.

              dgit's  build  operations  access the network, to get the -v option right.  See -v,
              below.

       dgit build-source ...
              Builds the source package, and a changes file for a prospective source-only upload,
              using    dpkg-source.     The   output   is   left   in   package_version.dsc   and
              package_version_source.changes.

              Tagging, signing and actually uploading should be left to dgit push-source, or dgit
              push.

       dgit clean
              Cleans the current working tree (according to the --clean= option in force).

       dgit update-vcs-git [suite|.] [--] [git fetch options]
       dgit update-vcs-git [suite|.] -
              Sets  up,  or  updates the url of, the vcs-git remote, and (unless - was specified)
              runs git fetch on it.

              By default, the Vcs-Git field of the .dsc from Debian  sid  is  used,  as  that  is
              probably  most  up to date.  Another suite may be specified, or .  to indicate that
              the Vcs-Git of the cwd's debian/control should be used instead.

       dgit help
              Print a usage summary.

       dgit sbuild ...
              Constructs the source  package,  uses  sbuild  to  do  a  binary  build,  and  uses
              mergechanges  to  merge the source and binary changes files.  Options and arguments
              after  sbuild  will  be  passed  on   to   sbuild.    The   output   is   left   in
              package_version_multi.changes.

              Note that by default sbuild does not build arch-independent packages.  You probably
              want to pass -A, to request those.

              Tagging, signing and actually uploading should be left to dgit push.

       dgit pbuilder [debbuildopts]
              Constructs the source package, uses  pbuilder  to  do  a  binary  build,  and  uses
              mergechanges  to  merge the source and binary changes files.  The output is left in
              package_version_multi.changes.

              You should ensure that your dgit --build-products-dir setting matches your pbuilder
              --buildresult.

              The  debbuildopts  are  passed to pbuilder using its --debbuildopts option.  If you
              want to pass other  options  to  pbuilder,  use  the  --pbuilder:  dgit  option  as
              described  below  (remember  that  dgit  options  should  appear  between  dgit and
              pbuilder).

              You  should  ensure  that  in  your  pbuilderrc  you  do  not  have   the   setting
              SOURCE_ONLY_CHANGES=yes as this may cause trouble.

       dgit cowbuilder [debbuildopts]
              Like dgit pbuilder, but uses cowbuilder instead of pbuilder.

       dgit gbp-build ...
              Runs git-buildpackage with some suitable options.  Options and arguments after gbp-
              build will be passed on to git-buildpackage.

              By default this uses --quilt=gbp,  so  HEAD  should  be  a  git-buildpackage  style
              branch, not a patches-applied branch.

              Tagging, signing and actually uploading should be left to dgit push.

       dgit push [suite]
              Does an `upload', pushing the current HEAD to the archive (as a source package) and
              to dgit-repos (as git commits).  The package must already have been built ready for
              upload,  with  the  .dsc and .changes left in the parent directory.  It is normally
              best to do the build with dgit too (eg with dgit sbuild): some existing build tools
              pass  unhelpful  options  to  dpkg-source et al by default, which can result in the
              built source package not being identical to the git tree.

              In more detail: dgit push checks that the current HEAD corresponds to the .dsc.  It
              then  pushes  the  HEAD  to  the suite's dgit-repos branch, adjusts the .changes to
              include any .origs which the archive lacks and exclude .origs which the archive has
              (so  -sa  and  -sd  are not needed when building for dgit push), makes a signed git
              tag, edits the .dsc to contain the dgit metadata field, runs debsign  to  sign  the
              upload  (.dsc and .changes), pushes the signed tag, and finally uses dput to upload
              the .changes to the archive.

              dgit  push  always  uses  the  package,  suite  and  version   specified   in   the
              debian/changelog  and  the .dsc, which must agree.  If the command line specifies a
              suite then that must match too.

              When used on a git-debrebase branch, dgit calls git-debrebase to prepare the branch
              for source package upload and push.

       dgit push-source [suite]
              Without -C, builds a source package and dgit pushes it.  Saying dgit push-source is
              like saying "update the source code in the archive to match my git  HEAD,  and  let
              the autobuilders do the rest."

              With  -C,  performs  a dgit push, additionally ensuring that no binary packages are
              uploaded.

       dgit rpush build-host:build-dir [push args...]
              Pushes the contents of the specified directory on a remote machine.  This  is  like
              running  dgit  push on build-host with build-dir as the current directory; however,
              signing operations are done on the invoking host.  This allows you  to  do  a  push
              when  the  system  which has the source code and the build outputs has no access to
              the key:

              1.   Clone on build host (dgit clone)
              2.   Edit code on build host (edit, git commit)
              3.   Build package on build host (dgit build)
              4.   Test package on build host or elsewhere (dpkg -i, test)
              5.   Upload by invoking dgit rpush on host with your GPG key.

              However, the build-host must be able to ssh to the dgit  repos.   If  this  is  not
              already  the  case,  you must organise it separately, for example by the use of ssh
              agent forwarding.

              The remaining arguments are treated just as dgit push would handle them.

              build-host and build-dir can be passed as separate arguments; this is assumed to be
              the case if the first argument contains no : (except perhaps one in [ ], to support
              IPv6 address literals).

              You will need similar enough versions of dgit on the build-host and the  invocation
              host.   The  build-host  needs gnupg installed, with your public key in its keyring
              (but not your private key, obviously).

       dgit setup-new-tree
              Configure the current working tree the way that dgit clone would have  set  it  up.
              Like  running  dgit  setup-useremail, setup-mergechangelogs and setup-gitattributes
              (but only does each thing if dgit is configured to do it automatically).   You  can
              use these in any git repository, not just ones used with the other dgit operations.
              Does not run update-vcs-git (as that requires Debian packaging information).

       dgit setup-useremail
              Set the working tree's user.name  and  user.email  from  the  distro-specific  dgit
              configuration  (dgit-distro.distro.user-name  and  .user-email),  or DEBFULLNAME or
              DEBEMAIL.

       dgit setup-mergechangelogs
              Configures a git merge helper  for  the  file  debian/changelog  which  uses  dpkg-
              mergechangelogs.

       dgit setup-gitattributes
              Set  up  the  working  tree's  .git/info/attributes  to  disable  all  transforming
              attributes for all files.  This is done by defining a macro attribute, dgit-defuse-
              attrs,  and  applying  it  to *.  For why, see GITATTRIBUTES in dgit(7).  Note that
              only attributes affecting the working tree are suppressed.  git-archive may  remain
              exciting.

              If   there   is   an  existing  macro  attribute  line  [attr]dgit-defuse-attrs  in
              .git/info/attributes, but it is insufficient, because it was  made  by  an  earlier
              version  of  dgit  and  git  has since introduced new transforming attributes, this
              modifies the macro to disable the newer transformations.

              (If  there  is  already  a  macro   attribute   line   [attr]dgit-defuse-attrs   in
              .git/info/attributes  which  does  what  dgit requires (whatever files it effects),
              this operation does nothing further.  This fact can be used to defeat or  partially
              defeat dgit setup-gitattributes and hence dgit setup-new-tree.)

       dgit quilt-fixup
              `3.0 (quilt)' format source packages need changes representing not only in-tree but
              also as patches in debian/patches.  dgit quilt-fixup checks whether this  has  been
              done;  if not, dgit will make appropriate patches in debian/patches and also commit
              the resulting changes to git.

              This is normally done automatically by dgit build and dgit push.

              dgit will try to turn each relevant commit in your git history  into  a  new  quilt
              patch.   dgit  cannot  convert  nontrivial  merges,  or certain other kinds of more
              exotic history.  If dgit can't find a suitable linearisation of  your  history,  by
              default  it  will  fail,  but  you  can  ask it to generate a single squashed patch
              instead.

              When used with a git-debrebase branch,  dgit  will  ask  git-debrebase  to  prepare
              patches.   However,  dgit  can  make patches in some situations where git-debrebase
              fails, so dgit quilt-fixup can be useful in its own right.  To  always  use  dgit's
              own   patch   generator   instead   of   git-debrebase  make-patches,  pass  --git-
              debrebase=true to dgit.

              See FORMAT 3.0 (QUILT) in dgit(7).

       dgit import-dsc [sub-options] ../path/to/.dsc [+|..]branch
              Import a Debian-format source package, specified by its .dsc,  into  git,  the  way
              dgit fetch would do.

              This  does  about half the work of dgit fetch: it will convert the .dsc into a new,
              orphan git branch.  Since dgit has no access  to  a  corresponding  source  package
              archive  or  knowledge  of the history it does not consider whether this version is
              newer than any previous import or corresponding git branches; and it therefore does
              not make a pseudomerge to bind the import into any existing git history.

              Because  a  .dsc  can contain a Dgit field naming a git commit (which you might not
              have), and specifying where to find that commit (and any  history  rewrite  table),
              import-dsc  might  need  online access.  If this is a problem (or dgit's efforts to
              find the commit fail), consider --no-chase-dsc-distro  or  --force-import-dsc-with-
              dgit-field.

              There is only one sub-option:

              --require-valid-signature  causes  dgit to insist that the signature on the .dsc is
              valid (using the same criteria as dpkg-source -x).  Otherwise, dgit tries to verify
              the signature but the outcome is reported only as messages to stderr.

              If  branch  is  prefixed  with  +  then  if  it  already  exists, it will be simply
              overwritten, no matter its existing contents.  If branch is prefixed with ..   then
              if  it already exists and dgit actually imports the dsc (rather than simply reading
              the git commit out of the Dgit field), dgit will make a  pseudomerge  so  that  the
              result  is necessarily fast forward from the existing branch.  Otherwise, if branch
              already exists, dgit will stop with an error message.

              If branch does not start with refs/, refs/heads/ is prepended.

       dgit version
              Prints version information and exits.

       dgit clone-dgit-repos-server destdir
              Tries to fetch a copy of the source code for  the  dgit-repos-server,  as  actually
              being used on the dgit git server, as a git tree.

       dgit print-dgit-repos-server-source-url
              Prints  the  url  used by dgit clone-dgit-repos-server.  This is hopefully suitable
              for use as a git remote url.  It may not be useable in a browser.

       dgit print-dpkg-source-ignores
              Prints the -i and -I arguments which must be passed to dpkg-souce to  cause  it  to
              exclude  exactly  the  .git directory and nothing else.  The separate arguments are
              unquoted, separated by spaces, and do not contain spaces.

       dgit print-unapplied-treeish
              Constructs a tree-ish approximating the patches-unapplied state of your 3.0 (quilt)
              package, and prints the git object name to stdout.  This requires appropriate .orig
              tarballs.  This tree object is identical to your .origs as regards upstream  files.
              The  contents  of  the  debian  subdirectory  is  not interesting and should not be
              inspected; except that debian/patches will be identical to your HEAD.

              To make this operate off-line, the  access  configuration  key  which  is  used  to
              determine  the  build-products-dir is the uncanonicalised version of the suite name
              from the changelog, or (of  course)  dgit.default.build-products-dir.   See  ACCESS
              CONFIGURATION, below.

              This function is primarily provided for the benefit of git-debrebase.

OPTIONS

       --dry-run | -n
              Go through the motions, fetching all information needed, but do not actually update
              the output(s).  For push, dgit does the required checks and leaves the new .dsc  in
              a temporary file, but does not sign, tag, push or upload.

       --damp-run | -L
              Go  through  many  more  of  the motions: do everything that doesn't involve either
              signing things, or making changes on the public servers.

       -kkeyid
              Use keyid for signing the tag and the upload.  The default comes from the  distro's
              keyid  config  setting  (see  CONFIGURATION,  below), or failing that, the uploader
              trailer line in debian/changelog.

       --no-sign
              does not sign tags or uploads (meaningful only with push).

       -ppackage
              Specifies that we should process source package  package  rather  than  looking  in
              debian/control or debian/changelog.  Valid with dgit fetch and dgit pull, only.

       --clean=git | -wg
              Use  git  clean  -xdf  to clean the working tree, rather than running the package's
              rules clean target.

              This will delete all files which are not tracked by git.  (Including any files  you
              forgot to git add.)

              --clean=...   options  other  than  dpkg-source are useful when the package's clean
              target is troublesome, or to avoid needing the build-dependencies.

              dgit will only actually clean the tree if it needs to (because it  needs  to  build
              the  source  package  or  binaries from your working tree).  Otherwise it will just
              check that there are no untracked unignored  files.   See  --clean=git[-ff],always,
              below.

       --clean=git-ff | -wgf
              Use  git  clean  -xdff  to clean the working tree.  Like git clean -xdf but it also
              removes any subdirectories containing  different  git  trees  (which  only  unusual
              packages are likely to create).

       --clean=git[-ff],always | -wga | -wgfa
              Like  --clean=git,  but  always  does  the clean and not just a check, deleting any
              untracked un-ignored files.

       --clean=check | --clean=check,ignores | -wc | -wci
              Merely check that the tree is clean (does not contain uncommitted  files).   Avoids
              running rules clean, and can avoid needing the build-dependencies.

              With ,ignores or -wci, untracked files covered by .gitignore are tolerated, so only
              files which show up as ?  in git status (ie, ones you maybe forgot to git add)  are
              treated as a problem.

       --clean=none | -wn
              Do not clean the tree, nor check that it is clean.  Avoids running rules clean, and
              can avoid needing the build-dependencies.  If there are files which are not in git,
              or if the build creates such files, a subsequent dgit push will fail.

       --clean=dpkg-source[-d] | -wd | -wdd
              Use  dpkg-buildpackage  to  do  the clean, so that the source package is cleaned by
              dpkg-source  running  the  package's  clean  target.   --clean=dpkg-source  is  the
              default.

              Without the extra d, requires the package's build dependencies.

              With  ...-d  or  -wdd, the build-dependencies are not checked (due to passing -d to
              dpkg-buildpackage), which violates policy, but may work in practice.

              The rules clean target will only be run if it is needed:  when  dgit  is  going  to
              build  source  or binary packages from your working tree, rather than from your git
              branch (for example because of --include-dirty or because the binary package  build
              uses your working tree).

              In  all cases, dgit will check that there are (after rules clean, if applicable) no
              untracked un-ignored files, in case these are files you forgot to git add.  (Except
              that  this  check  is  not  done for a `3.0 (quilt)' package when dgit has to apply
              patches, dirtily, to the working tree.)  If your  package  does  not  have  a  good
              .gitignore you will probably need --clean=dpkg-source,no-check aka -wdn.

       --clean=dpkg-source[-d],no-check | -wdn | -wddn
              Like --clean=dpkg-source, but does not care about untracked un-ignored files.

       --clean=dpkg-source[-d],all-check | -wda | -wdda
              Like  --clean=dpkg-source,  but  fails even on ignored untracked files.  This could
              perhaps be used to detect bugs in your rules clean target.

       -N | --new
              The package is or may be new in this suite.  Without  this,  dgit  will  refuse  to
              push.   It  may  (for  Debian,  will)  be  unable to access the git history for any
              packages which have been newly pushed and have not yet been published.

       --include-dirty
              Do not complain if the working  tree  does  not  match  your  git  HEAD,  and  when
              building,  include  the  changes  from  your working tree.  This can be useful with
              build, if you plan to commit later.  (dgit push will still ensure that the .dsc you
              upload  and  the  git tree you push are identical, so this option won't make broken
              pushes.)

              Note that this does not prevent dgit from cleaning your tree, so if the changes  in
              your working tree are in the form of untracked files, those might still be deleted,
              especially with --clean=git.  If you want to include untracked files in the  build,
              you can use --clean=none or --clean=dpkg-source[-d] in addition to --include-dirty.
              Note  that  this  combination  can  fail  if  the   untracked   files   are   under
              debian/patches/.

       --ignore-dirty
              Deprecated alias for --include-dirty.

       --overwrite[=previous-version]
              Declare  that  your  HEAD  really  does  contain  all the (wanted) changes from all
              versions listed in its changelog; or, all (wanted) changes  from  previous-version.
              This  promise  is needed when your git branch is not a descendant of the version in
              the archive according to the git revision history.

              It is safer not to specify previous-version, and usually it's not needed.  Just say
              --overwrite, unless you know what you are doing.

              This  option  is  useful  if  you are the maintainer, and you have incorporated NMU
              changes into your own git workflow in a way that doesn't make your  branch  a  fast
              forward from the NMU.

              This  option is also usually necessary the first time a package is pushed with dgit
              push to a particular suite.  See dgit-maint-*(7).

              If previous-version is not specified, dgit will  check  that  the  version  in  the
              archive  is  mentioned  in your debian/changelog.  (This will avoid losing changes,
              even with --overwrite, unless someone committed to git a finalised changelog entry,
              and then made later changes to that version.)  If previous-version is specified, it
              ought to be the version currently in the archive.

              dgit push --overwrite will, if necessary, make a pseudo-merge (that  is,  something
              that  looks  like  the result of git merge -s ours) to stitch the archive's version
              into your own git history, so that your push is a fast forward from the archive.

              (In quilt mode gbp, dpm, unpatched or baredebian*, implying  a  split  between  the
              dgit  view  and  the maintainer view, the pseudo-merge will appear only in the dgit
              view.)

       --delayed=days
              Upload to a DELAYED queue.

              WARNING: If the maintainer responds by cancelling your upload from the  queue,  and
              does  not  make  an upload of their own, this will not rewind the git branch on the
              dgit git server.  Other dgit users will then see your push (with a warning  message
              from  dgit)  even  though  the  maintainer  wanted to abolish it.  Such users might
              unwittingly reintroduce your changes.

              If this situation arises, someone should make a suitable dgit push  to  update  the
              contents of dgit-repos to a version without the controversial changes.

       --no-chase-dsc-distro
              Tells   dgit  not  to  look  online  for  additional  git  repositories  containing
              information about a particular .dsc being imported.  Chasing is the default.

              For most operations (such as fetch and pull), disabling  chasing  means  dgit  will
              access  only  the  git server for the distro you are directly working with, even if
              the .dsc was copied  verbatim  from  another  distro.   For  import-dsc,  disabling
              chasing means dgit will work completely offline.

              Disabling  chasing  can be hazardous: if the .dsc names a git commit which has been
              rewritten by those in charge of the distro, this option may  prevent  that  rewrite
              from  being  effective.   Also,  it  can mean that dgit fails to find necessary git
              commits.

       --save-dgit-view=branch|ref
              Specifies that when split view is in operation, and dgit calculates (or looks up in
              its  cache)  a  dgit view corresponding to your HEAD, the dgit view will be left in
              ref.  The specified ref is unconditionally overwritten, so don't specify  a  branch
              you want to keep.

              This option is effective only with the following operations: quilt-fixup; push; all
              builds.  And it is only effective when split view is actually in operation.

              If ref does not start with refs/ it is taken to be a branch - i.e.  refs/heads/  is
              prepended.

              --dgit-view-save is a deprecated alias for --save-dgit-view.

       --deliberately-something
              Declare  that  you  are deliberately doing something.  This can be used to override
              safety catches, including safety catches which relate to distro-specific  policies.
              The  use  of  --deliberately is declared and published in the signed tags generated
              for you by dgit, so that the archive software can give effect to your  intent,  and
              for  the  benefit  of  humans  looking  at the history.  The meanings of somethings
              understood in the context of Debian are discussed below:

       --deliberately-not-fast-forward
              Declare that you are deliberately rewinding history.  When pushing to  Debian,  use
              this  when  you are making a renewed upload of an entirely new source package whose
              previous version was not accepted for release from NEW  because  of  problems  with
              copyright or redistributibility.

              When  split  view is in operation, this also prevents the construction by dgit of a
              pseudomerge  to  make  the  dgit  view  fast  forwarding.   Normally  only  one  of
              --overwrite  (which  creates  a  suitable pseudomerge) and --deliberately-not-fast-
              forward (which suppresses the pseudomerge and the fast forward  checks)  should  be
              needed; --overwrite is usually better.

       --deliberately-include-questionable-history
              Declare  that  you  are  deliberately including, in the git history of your current
              push, history which contains a previously-submitted version of this  package  which
              was not approved (or has not yet been approved) by the ftpmasters.  When pushing to
              Debian, only use this option after verifying that: none  of  the  rejected-from-NEW
              (or never-accepted) versions in the git history of your current push, were rejected
              by ftpmaster for copyright or redistributability reasons.

       --deliberately-fresh-repo
              Declare that you are deliberately rewinding history and  want  to  throw  away  the
              existing  repo.   Not relevant when pushing to Debian, as the Debian server will do
              this automatically when necessary.

       --quilt=linear
              When fixing up source format `3.0 (quilt)' metadata, insist on generating a  linear
              patch  stack:  one  new  patch for each relevant commit.  If such a stack cannot be
              generated, fail.  This is the default for Debian.

              HEAD should be a series  of  plain  commits  (not  touching  debian/patches/),  and
              pseudomerges, with as ancestor a patches-applied branch.

       --quilt=auto
              When  fixing  up  source format `3.0 (quilt)' metadata, prefer to generate a linear
              patch stack (as with --quilt=linear) but if that  doesn't  seem  possible,  try  to
              generate  a  single  squashed  patch  for  all  the  changes  made  in git (as with
              --quilt=smash).  This is not a good idea for an NMU in Debian.

       --quilt=smash
              When fixing up source format `3.0 (quilt)' metadata, generate a  single  additional
              patch  for  all  the  changes  made  in git.  This is not a good idea for an NMU in
              Debian.

              (If HEAD has any in-tree patches already, they must apply cleanly.   This  will  be
              the  case  for  any trees produced by dgit fetch or clone; if you do not change the
              upstream version nor make changes in debian/patches, it will remain true.)

       --quilt=nofix
              Check whether source format `3.0 (quilt)' metadata would need fixing up, but, if it
              does,  fail.   You must then fix the metadata yourself somehow before pushing.  (NB
              that dpkg-source --commit will not work because the dgit git tree does not  have  a
              .pc directory.)

       --quilt=nocheck | --no-quilt-fixup
              Do  not check whether source format `3.0 (quilt)' metadata needs fixing up.  If you
              use this option and the metadata did in fact need fixing up, dgit push will fail.

       --[quilt=]gbp | --[quilt=]dpm | --quilt=unapplied | --[quilt=]baredebian[+git|+tarball]
              Tell dgit that you are using a nearly-dgit-compatible git branch, aka a  maintainer
              view, and do not want your branch changed by dgit.

              These quilt modes are known as splitting quilt modes.  See --split-view, below.

              --gbp  (short  for  --quilt=gbp)  is  for  use with git-buildpackage.  Your HEAD is
              expected to be a patches-unapplied git branch, except that it might contain changes
              to upstream .gitignore files.  This is the default for dgit gbp-build.

              --dpm (short for --quilt=dpm) is for use with git-dpm.  Your HEAD is expected to be
              a patches-applied git branch, except that it  might  contain  changes  to  upstream
              .gitignore files.

              --quilt=unapplied  specifies  that your HEAD is a patches-unapplied git branch (and
              that any changes to  upstream  .gitignore  files  are  represented  as  patches  in
              debian/patches).

              --quilt=baredebian  (or  its alias --quilt=baredebian+git) specifies that your HEAD
              contains only a debian/ directory, with any changes to upstream  files  represented
              as  patches  in  debian/patches.   The upstream source must be available in git, by
              default, in a suitably named git tag; see --upstream-commitish.  In this mode, dgit
              cannot  check  that  all edited upstream files are properly represented as patches:
              dgit relies on debian/patches being correct.

              --quilt=baredebian+tarball is like --quilt=baredebian, but is used when there is no
              appropriate  upstream  git  history.   To construct the dgit view, dgit will import
              your orig tarballs' contents into git.  In this mode, dgit cannot  check  that  the
              upstream  parts  of  your  upload correspond to what you intend: dgit relies on the
              right orig tarball(s) existing, and debian/patches being correct.

              With --quilt=gbp|dpm|unapplied|baredebian*, dgit push (or  precursors  like  quilt-
              fixup  and  build) will automatically generate a conversion of your git branch into
              the right form.  dgit push will push the dgit-compatible form (the  dgit  view)  to
              the  dgit  git  server.   The  dgit  view will be visible to you in the dgit remote
              tracking branches, but your own branch will not be modified.  dgit push will create
              a    tag   debian/version   for   the   maintainer   view,   and   the   dgit   tag
              archive/debian/version for the dgit view.  dgit quilt-fixup  will  merely  do  some
              checks, and cache the maintainer view.

              If  you have a branch like this it is essential to specify the appropriate --quilt=
              option!  This is because it is not always possible to tell: a patches-unapplied git
              branch  of a package with one patch, for example, looks very like a patches-applied
              branch where the user has used git revert to undo the patch, expecting to  actually
              revert  it.   However,  if  you  fail  to specify the right --quilt option, and you
              aren't too lucky, dgit will notice the problem and stop, with a useful hint.

       -ddistro | --distro=distro
              Specifies that the suite to  be  operated  on  is  part  of  distro  distro.   This
              overrides   the   default   value   found   from   the   git  config  option  dgit-
              suite.suite.distro.  The only effect is that other  configuration  variables  (used
              for accessing the archive and dgit-repos) used are dgit-distro.distro.*.

              If  your  suite is part of a distro that dgit already knows about, you can use this
              option to make dgit work even if your dgit  doesn't  know  about  the  suite.   For
              example,  specifying  -ddebian  will work when the suite is an unknown suite in the
              Debian archive.

              To define a new distro it is necessary to define  methods  and  URLs  for  fetching
              (and,  for dgit push, altering) a variety of information both in the archive and in
              dgit-repos.  How to set this up is not yet documented.

       --split-view=auto|always|never
              Controls whether dgit operates a split view, separating your own branch (as  Debian
              maintainer) from that shown to users of dgit clone and dgit fetch.

              When  split  view is in operation dgit will not make or merge any commits onto your
              own branch.  Specifically, only the dgit view  will  contain  dgit's  pseudomerges,
              which  bring  into  the  git  history previous uploads made with dgit push, and any
              commits in debian/patches required to make a correct `3.0 (quilt)' source package.

              auto is the default, and splits the view only  when  needed:  i.e.,  when  you  are
              working   with  a  `3.0  (quilt)'  source  package  and  a  splitting  quilt  mode:
              --[quilt=]gbp, dpm, unpatched or baredebian*.

              always splits the view regardless of the source format and the quilt mode.

              never will cause dgit to fail if split view is needed.

              When split view is in operation, the dgit view is visible in your local git  clone,
              but   only   in   refs   specific  to  dgit:  notably  remotes/dgit/dgit/suite  and
              archive/distro/version.

              Note that split view does not affect dgit fetch, and is not  compatible  with  dgit
              pull.

       -Cchangesfile
              Specifies  the  .changes  file which is to be uploaded.  By default dgit push looks
              for a single .changes file in the parent directory whose filename  suggests  it  is
              for the right package and version.

              If  the specified changesfile pathname contains slashes, the directory part is also
              used as the value for --build-products-dir; otherwise, the changes file is expected
              in that directory (by default, in ..).

       --upstream-commitish=upstream
              For use with --quilt=baredebian only.  Specifies the commit containing the upstream
              source.  This commit must be identical to your .orig tarball.  The  default  is  to
              look  for  one  of  the  git  tags  U vU upstream/U (in that order), where U is the
              upstream version.

       --rm-old-changes
              When doing a build, delete any  changes  files  matching  package_version_*.changes
              before  starting.   This  ensures  that dgit push (and dgit sbuild) will be able to
              unambiguously identify the relevant changes files from the most recent build,  even
              if there have been previous builds with different tools or options.  The default is
              not to remove, but --no-rm-old-changes can be used to override a previous --rm-old-
              changes or the .rm-old-changes configuration setting.

              Note  that dgit push-source will always find the right .changes, regardless of this
              option.

       --build-products-dir=directory
              Specifies where to find and create  tarballs,  binary  packages,  source  packages,
              .changes files, and so on.

              By default, dgit uses the parent directory (..).

              Changing  this  setting may necessitate moving .orig tarballs to the new directory,
              so it is probably best to  use  the  dgit.default.build-products-dir  configuration
              setting (see CONFIGURATION, below) which this command line option overrides).

       --no-rm-on-error
              Do not delete the destination directory if clone fails.

       --dep14tag
              Generates   a   DEP-14   tag  (eg  debian/version)  as  well  as  a  dgit  tag  (eg
              archive/debian/version).  This is the default.

       --no-dep14tag
              Do not generate a DEP-14 tag, except when split view is in operation.

       --always-dep14tag
              Obsolete alias for --dep14tag, retained for compatibility.

       -D     Prints debugging information to stderr.  Repeating the option produces more  output
              (currently, up to -DDDD is meaningfully different).

       -cname=value
              Specifies a git configuration option, to be used for this run.  dgit itself is also
              controlled by git configuration options.

       -vversion|_ | --since-version=version|_
              Specifies the -vversion option to pass to dpkg-genchanges, during builds.   Changes
              (from  debian/changelog)  since  this version will be included in the built changes
              file, and hence in the upload.  If this option is not specified,  dgit  will  query
              the archive and use the latest version uploaded to the intended suite.

              Specifying  _ inhibits this, so that no -v option will be passed to dpkg-genchanges
              (and as a result, only the last stanza from debian/changelog will be used  for  the
              build and upload).

       -mmaintaineraddress
              Passed to dpkg-genchanges (eventually).

       --ch:option
              Specifies a single additional option to pass, eventually, to dpkg-genchanges.

              Options  which  are  safe  to  pass include -C (and also -si -sa -sd although these
              should never be necessary with Debian since dgit automatically  calculates  whether
              .origs need to be uploaded.)

              For other options the caveat below applies.

       --curl:option | --dput:option |...
              Specifies  a  single additional option to pass to curl, dput, debsign, dpkg-source,
              dpkg-buildpackage, dpkg-genchanges, sbuild, pbuilder, cowbuilder, ssh,  dgit,  git-
              debrebase, apt-get, apt-cache, gbp-pq, gbp-build, or mergechanges.  Can be repeated
              as necessary.

              Use of this ability should not normally be necessary.  It is provided  for  working
              around  bugs,  or  other  unusual  situations.   If  you use these options, you may
              violate dgit's assumptions  about  the  behaviour  of  its  subprograms  and  cause
              lossage.

              For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, the option applies
              only when the program is invoked directly by dgit.  Usually, for passing options to
              dpkg-genchanges, you should use --ch:option.

              Specifying  --git  is  not  effective for some lower-level read-only git operations
              performed by dgit, and also not when git is invoked by another program run by dgit.

              See notes below regarding ssh and dgit.

              NB that  --gpg:option  is  not  supported  (because  debsign  does  not  have  that
              facility).  But see -k and the keyid distro config setting.

       --curl!:option | --dput!:option |...
              Specifies  an  option to remove from the command line for a program called by dgit,
              as for --program:option (and the same caveats apply).

              Any options or arguments exactly identical to option are removed.  (It  is  not  an
              error if there were none.)

              This can only be used to delete options which are always passed by default by dgit,
              or to undo a previous --program:option.  It cannot be used  to  override  option(s)
              dynamically decided on by dgit.

       --curl=program | --dput=program |...
              Specifies  alternative programs to use instead of curl, dput, debsign, dpkg-source,
              dpkg-buildpackage, dpkg-genchanges, sbuild, pbuilder, cowbuilder, gpg,  ssh,  dgit,
              git-debrebase, apt-get, apt-cache, git, gbp-pq, gbp-build, or mergechanges.

              For  dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, this applies only
              when the program is invoked directly by dgit.

              For dgit, specifies the command to run on the remote host when dgit rpush needs  to
              invoke  a  remote  copy  of  itself.  (dgit also reinvokes itself as the EDITOR for
              dpkg-source --commit; this is done using argv[0], and is not affected by --dgit=).

              gbp-build's value is used instead of gbp build or git-buildpackage.   (The  default
              is the latter unless the former exists on PATH.)  gbp-pq's value is used instead of
              gbp pq.  In both cases, unusually, the specified value is split  on  whitespace  to
              produce a command and possibly some options and/or arguments.

              For  pbuilder  and  cowbuilder,  the  defaults  are  sudo  -E  pbuilder and sudo -E
              cowbuilder respectively.  Like with gbp-build and gbp pq, the  specified  value  is
              split on whitespace.

              For  ssh,  the  default  value  is  taken  from the DGIT_SSH or GIT_SSH environment
              variables, if set (see below).  And, for ssh, when accessing the archive and  dgit-
              repos,  this  command  line setting is overridden by the git config variables dgit-
              distro.distro.ssh and .dgit.default.ssh (which can in turn be overridden with  -c).
              Also,  when  dgit is using git to access dgit-repos, only git's idea of what ssh to
              use (eg, GIT_SSH) is relevant.

       --existing-package=package
              dgit push needs to canonicalise the suite name.  Sometimes, dgit lacks a way to ask
              the  archive  to  do this without knowing the name of an existing package.  Without
              --new we can just use the package we are trying to push.  But with --new that  will
              not  work,  so  we  guess dpkg or use the value of this option.  This option is not
              needed with the default mechanisms for accessing the archive.

       -h|--help
              Print a usage summary.

       --initiator-tempdir=directory
              dgit rpush uses a temporary directory on the invoking (signing) host.  This  option
              causes dgit to use directory instead.  Furthermore, the specified directory will be
              emptied, removed and recreated before dgit starts, rather than removed  after  dgit
              finishes.  The directory specified must be an absolute pathname.

       --force-something
              Instructs  dgit to try to proceed despite detecting what it thinks is going to be a
              fatal problem.  This is probably not going to work.  These options are provided  as
              an  escape hatch, in case dgit is confused.  (They might also be useful for testing
              error cases.)

       --force-import-dsc-with-dgit-field
              Tell dgit import-dsc to treat a .dsc with a Dgit field like one  without  it.   The
              result  is  a  fresh  import, discarding the git history that the person who pushed
              that .dsc was working with.

       --force-uploading-binaries
              Carry on and upload binaries even though dgit thinks your distro  does  not  permit
              that.

       --force-uploading-source-only
              Carry on and do a source-only upload, without any binaries, even though dgit thinks
              your distro does not permit that, or does not permit that in this situation.

       --force-unrepresentable
              Carry on even if dgit thinks that your git tree contains changes (relative to  your
              .orig  tarballs)  which  dpkg-source  is not able to represent.  Your build or push
              will probably fail later.

       --force-changes-origs-exactly
              Use the set of .origs specified in your .changes, exactly, without regard  to  what
              is in the archive already.  The archive may well reject your upload.

       --force-unsupported-source-format
              Carry  on  despite  dgit  not  understanding your source package format.  dgit will
              probably mishandle it.

       --force-dsc-changes-mismatch
              Do not check whether .dsc and .changes match.  The  archive  will  probably  reject
              your upload.

       --force-import-gitapply-absurd | --force-import-gitapply-no-absurd
              Force  on  or  off  the  use  of the absurd git-apply emulation when running gbp pq
              import when importing a package from a .dsc.  See Debian bug #841867.

CONFIGURATION

       dgit can be configured via the git config  system.   You  may  set  keys  with  git-config
       (either  in  system-global  or per-tree configuration), or provide -ckey=value on the dgit
       command line.

       Settings likely to be useful for an end user include:

       dgit.default.build-products-dir
              Specifies where to find the built files to be uploaded,  when  --build-products-dir
              is not specified.  The default is the parent directory (..).

       dgit-suite.suite.distro distro
              Specifies  the  distro for a suite.  dgit keys off the suite name (which appears in
              changelogs etc.), and uses that to determine the distro  which  is  involved.   The
              config used is thereafter that for the distro.

              suite may be a glob pattern.

       dgit.default.distro distro
              The default distro for an unknown suite.

       dgit.default.default-suite suite
              The default suite (eg for clone).

       dgit.default.*
              for  each  dgit-distro.distro.*,  the  default  value  used  if there is no distro-
              specific setting.

       dgit-distro.distro.clean-mode
              One of the values for the command line --clean= option;  used  if  --clean  is  not
              specified.

       dgit-distro.distro.clean-mode-newer
              Like  .clean-mode,  but  ignored  if  the value is unknown to this version of dgit.
              Setting both .clean-mode and .clean-mode-newer is useful to provide  a  single  git
              config compatible with different dgit versions.

       dgit-distro.distro.quilt-mode
              One  of  the  values  for  the command line --quilt= option; used if --quilt is not
              specified.

       dgit-distro.distro.split-view

       dgit-distro.distro.rm-old-changes
              Boolean, used if neither --rm-old-changes  nor  --no-rm-old-changes  is  specified.
              The default is not to remove.

       dgit-distro.distro.readonly auto|a | true|t|y|1 | false|f|n|0
              Whether  you  have  push  access  to the distro.  For Debian, it is OK to use auto,
              which uses readonly mode if you are not pushing right now;  but,  setting  this  to
              false will avoid relying on the mirror of the dgit git repository server.

       dgit-distro.distro.keyid
              See also -k.

       dgit-distro.distro.mirror url

       dgit-distro.distro.username
              Not relevant for Debian.

       dgit-distro.distro.upload-host
              Might be useful if you have an intermediate queue server.

       dgit-distro.distro.user-name dgit-distro.distro.user-email
              Values  to  configure  for  user.name  and  user.email  in  new  git trees.  If not
              specified,  the  DEBFULLNAME  and  DEBEMAIL   environment   variables   are   used,
              respectively.  Only used if .setup-usermail is not disabled.

       dgit-distro.distro.setup-useremail
              Whether  to  set  user.name  and  user.email  in  new  git trees.  True by default.
              Ignored for dgit setup-useremail, which does it anyway.

       dgit-distro.distro.setup-mergechangelogs
              Whether  to  set  up  a  merge   driver   which   uses   dpkg-mergechangelogs   for
              debian/changelog.   True by default.  Ignored for dgit setup-mergechangelogs, which
              does it anyway.

       dgit-distro.distro.setup-gitattributes
              Whether to configure .git/info/attributes to suppress checkin/checkout file content
              transformations  in  new  git  trees.   True  by  default.  Ignored for dgit setup-
              gitattributes, which does it anyway.

       dgit-distro.distro.cmd-cmd
              Program to use instead of cmd.  Works like --cmd=... .

       dgit-distro.distro.opts-cmd
              Extra options to pass to cmd.  Works like --cmd:... .   To  pass  several  options,
              configure  multiple  values in git config (with git config --add).  The options for
              dgit.default.opts-cmd and dgit-distro.distro/push.opts-cmd are all  used,  followed
              by options from dgit's command line.

ACCESS CONFIGURATION

       There  are  many  other settings which specify how a particular distro's services (archive
       and git) are provided.  These should not normally be adjusted, but are documented for  the
       benefit of distros who wish to adopt dgit.

       dgit-distro.distro.nominal-distro
              Shown in git tags, Dgit fields, and so on.

       dgit-distro.distro.alias-canon
              Used for all access configuration lookup.

       dgit-distro.distro/push.*
              If  set,  overrides  corresponding  non  /push  config when readonly=false, or when
              pushing and readonly=auto.

       dgit-distro.distro.git-url

       dgit-distro.distro.git-url[-suffix]

       dgit-distro.distro.git-proto

       dgit-distro.distro.git-path

       dgit-distro.distro.git-check true|false|url|ssh-cmd

       dgit-distro.distro.git-check-suffix

       dgit-distro.distro.diverts.divert new-distro|/distro-suffix

       dgit-distro.distro.git-create ssh-cmd|true

       dgit-distro.distro.archive-query  ftpmasterapi:  |  madison:distro  |  dummycat:/path    |
       sshpsql:user@host:dbname

       dgit-distro.distro.archive-query-(url|tls-key|curl-ca-args)

       dgit-distro.distro.madison-distro

       dgit-distro.distro.archive-query-default-component

       dgit-distro.distro.dgit-tag-format

       dgit-distro.distro.dep14tag want|no[|always]

       dgit-distro.distro.ssh

       dgit-distro.distro.sshpsql-dbname

       dgit-distro.distro.(git|sshpsql)-(user|host|user-force)

       dgit-distro.distro.backports-quirk

       dgit-distro.distro.rewrite-map-enable

       dgit-distro.distro.source-only-uploads ok|always|never|not-wholly-new

       dgit.default.old-dsc-distro

       dgit.dsc-url-proto-ok.protocol

       dgit.dsc-url-proto-ok.bad-syntax

       dgit.default.dsc-url-proto-ok

       dgit.vcs-git.suites suite[;...]

ENVIRONMENT VARIABLES

       DGIT_SSH, GIT_SSH
              specify  an  alternative  default program (and perhaps arguments) to use instead of
              ssh.  DGIT_SSH is consulted first and may contain arguments;  if  it  contains  any
              whitespace  will  be  passed  to the shell.  GIT_SSH specifies just the program; no
              arguments can be specified, so dgit interprets it the same way as  git  does.   See
              also the --ssh= and --ssh: options.

       DEBEMAIL, DEBFULLNAME
              Default git user.email and user.name for new trees.  See dgit setup-new-tree.

       gpg, dpkg-..., debsign, git, curl, dput, LWP::UserAgent
              and  other subprograms and modules used by dgit are affected by various environment
              variables.  Consult the documentation for those programs for details.

BUGS

       There should be a `dgit rebase-prep' command or some such to turn a fast-forwarding branch
       containing  pseudo-merges back into a rebasing patch stack.  It might have to leave a note
       for a future dgit push.

       If the dgit push fails halfway through, it is not necessarily restartable and  idempotent.
       It would be good to check that the proposed signing key is available before starting work.

       dgit's  build functions, and dgit push, may make changes to your current HEAD.  Sadly this
       is necessary for packages in the `3.0 (quilt)' source format.  This is ultimately  due  to
       what I consider design problems in quilt and dpkg-source.

       --dry-run  does  not always work properly, as not doing some of the git fetches may result
       in subsequent actions being different.  Doing a non-dry-run dgit fetch  first  will  help.
       --damp-run is likely to work much better.

SEE ALSO

       dgit(7),  dgit-*(7),  curl(1),  dput(1),  debsign(1),  git-config(1), git-buildpackage(1),
       dpkg-buildpackage(1),
       https://browse.dgit.debian.org/