Provided by: dpatch_2.0.38+nmu1_all bug

NAME

       dpatch-edit-patch - maintain dpatch patches for a Debian source package

SYNOPSIS

       dpatch-edit-patch [options] command dpatchname [basepatch]

DESCRIPTION

       This  manual  documents the dpatch-edit-patch command which maintains dpatch patches for a
       dpatch-using Debian source package.

       dpatch-edit-patch will copy the full tree to a temporary directory for working.

WARNING

       dpatch is deprecated, please switch to the `3.0  (quilt)'  Debian  source  package  format
       instead.  See http://wiki.debian.org/Projects/DebSrc3.0#FAQ for a short guide on how to do
       it.

OPTIONS

       dpatch-edit-patch takes two forms of arguments; options and commands.  Currently, the only
       command that exists is “patch”, which allows you to create/edit dpatches.  When no command
       is given, “patch” is assumed.

   COMMANDS:
       patch  This command requires one mandatory argument, and  accepts  one  optional  argument
              under certain circumstances.  The mandatory argument is dpatchname.  This refers to
              a dpatch, as it would be listed in debian/patches/00list.  It is not necessary  for
              dpatchname to exist prior to running dpatch-edit-patch patch dpatchname.

              When  dpatchname exists, dpatch-edit-patch will set up a working source tree, apply
              all dpatches listed in debian/patches/00list up to and  including  dpatchname,  and
              spawn  an  interactive  shell  for the developer. The developer then edits files in
              this  working  tree.  When  the  developer  is   done,   they   exit   the   shell.
              dpatch-edit-patch  then updates dpatchname to reflect the changes made.  Should the
              developer wish to abort the process from the  interactive  shell,  they  need  only
              cause  the  shell  to  exit  with an exit value of 230.  Typically, this is done by
              exiting the shell with the command exit 230.

              Would the developer wish to see the patch one's currently works on without  exiting
              the subshell, two environment variables are exported into the subshell to help with
              this: DPEP_SHELL_REFDIR, which is set to the reference directory's full  name,  and
              DPEP_SHELL_WORKDIR, which is set to the subshell's working directory.

              These  two  can  be  used  to - for example - generate a diff between the reference
              version and the current tree:

                     diff -urNa $DPEP_SHELL_REFDIR $DPEP_SHELL_WORKDIR

       When dpatchname does not exist, dpatch-edit-patch will assume that a new dpatch should  be
       created.  As  with  the  above  scenario, dpatch-edit-patch first creates a working source
       tree.   If   the   optional   argument   basepatch   is   supplied,   all   dpatches    in
       debian/patches/00list  up  to and including basepatch will be applied to the working tree.
       If basepatch is not supplied, no dpatches are applied to  the  working  tree.   When  then
       developer    exits    the   shell,   dpatch-edit-patch   will   create   dpatchname.    If
       debian/patches/00template does not exist, a hardcoded dpatch header and shell snippet will
       be  used. If it exists and is not executable, it will be copied verbatim as the header and
       shell snippet.

       Its first parameter is the base filename of  the  to-be-updated  or  to-be-created  dpatch
       (useful  for  adding  titles  to  the  dpatch  header).  Its  second parameter will be the
       description of the new patch.

   OPTIONS
       For the  following  options,  command-line  arguments  take  precedence  over  environment
       variables, which take precedence over configuration variables. Configuration variables are
       read from debian/patches/00dpatch.conf and ~/.dpatch.conf.

       -s, --sourcedir=value
              Directory  containing  unpacked  Debian  source  package.   Configuration  variable
              conf_sourcedir    (settable   only   in   ~/.dpatch.conf),   environment   variable
              DPEP_SOURCEDIR.  Defaults to the current working directory.

       -o, --outdir=value
              Directory where the updated or newly-created dpatch will be placed.   Configuration
              variable  conf_outdir  (~/.dpatch.conf), environment variable DPEP_OUTDIR. Defaults
              to ./debian/patches/

       -c, --clean
              Indicate to dpatch-edit-patch  that  the  current  work  directory  can  safely  be
              cleaned.  If  not  given,  dpatch-edit-patch  tries to preserve partial or complete
              builds by first copying the current work directory to a reference directory  before
              invoking  debian/rules  clean  on  the  reference  directory. If given, the current
              directory is cleaned and then taken as a reference directory. Use  this  option  if
              your  source  package  is  pretty  large  and  no  significant work is destroyed by
              cleaning. Configuration variable conf_clean (~/.dpatch.conf), Environment  variable
              DPEP_CLEAN.

       -b, --debianonly[=path]
              Indicate  to  dpatch-edit-patch  that  the  current  work directory only contains a
              debian subdirectory and that an upstream tarball is to be unpacked in the reference
              directory before copying the current work directory there. The optional argument is
              the path to the upstream tarball - including the  tarball  name.  If  no  value  is
              given,  dpatch-edit-patch  will use the hook script pointed to by conf_getorigtargz
              (~/.dpatch.conf) or DPEP_GETORIGTARGZ to obtain  the  upstream  tarball.  The  hook
              script  should  take  one  argument:  the  destination  directory where the fetched
              archive    shall    be    put.     Configuration     variables:     conf_debianonly
              (debian/patches/00dpatch.conf)  and  conf_origtargz  (~/.dpatch.conf),  Environment
              Variables DPEP_DEBIANONLY and DPEP_ORIGTARGZ.

       -P, --origtargzpath=path
              When -b is in use, specify the path where upstream tarballs should be  looked  for.
              path   is   a   colon-separated  list  of  directories.   Configuration  variables:
              conf_origtargzpath (~/.dpatch.conf), Environment Variables DPEP_ORIGTARGZPATH.

       -r, --rootcmd=value
              Command used to gain root privileges used to clean  DPEP_SOURCEDIR.   Configuration
              variable conf_rootcmd, environment variable DPEP_ROOTCMD.  Defaults to fakeroot, if
              installed.  If none of the above are specified,  and  fakeroot  is  not  installed,
              dpatch-edit-patch  will  abort.   The  dpatch authors strongly recommend the use of
              fakeroot for this purpose.

       -d, --description=value
              Description used for a newly-created patch.   Configuration  variable  conf_newdesc
              (~/.dpatch.conf), environment variable DPEP_NEWDESC, defaults to “No description.”

       -k, --keeptemp=value
              Boolean   value,   either   0   or   1.    Configuration   variable   conf_keeptemp
              (~/.dpatch.conf), environment variable DPEP_KEEPTEMP.  When  set  to  1,  temporary
              working tree is not deleted when dpatch-edit-patch is done.

       -t, --tmpdir=value
              Temporary  directory  within which dpatch-edit-patch will create the working source
              tree.  Configuration variable conf_tmpdir  (~/.dpatch.conf),  environment  variable
              DPEP_TMPDIR.  Should none of the above be set, dpatch-edit-patch will first attempt
              to use the environment variable TMPDIR, and will fall back to /tmp.

       -p, --stampdir=value
              The directory dpatch has used for creating patch  stamps.   Used  for  checking  if
              patch  to be edited is already applied to the working tree.  Configuration variable
              conf_stampdir (~/.dpatch.conf), environment variable DPEP_STAMPDIR. Should none  of
              the above be set, dpatch-edit-patch will fall back to debian/patched

       -e, --exclude=valuelist
              Space-separated  list  of  file-  and  directory  names that dpatch-edit-patch will
              exclude  from  being  copied  and  diffed.   Configuration  variable   conf_exclude
              (~/.dpatch.conf),  environment  variable  DPEP_EXCLUDE.  Defaults to "CVS .svn .git
              .arch .hg _darcs .bzr", which might cause you trouble if you use files  named  like
              that in your package.

       -O, --diffopts=valuelist
              Extra options to directly pass to diff as-is.  Configuration variable conf_diffopts
              (~/.dpatch.conf), environment variable DPEP_DIFF_OPTIONS. It is empty by default.

       -l, --shell=shell
              Tell dpatch-edit-patch which shell to  invoke.  Configuration  variable  conf_shell
              (~/.dpatch.conf),  environment  variable  DPEP_SHELL,  defaulting to $SHELL and the
              user's default shell.

       -n, --notimestamp
              Tell dpatch-edit-patch to remove timestamps from the diffs it generates.  Can  also
              be set in debian/patches/00options, with the DPEP_OMIT_TIMESTAMPS variable.

       -0, --add2list
              add the new patch to 00list file.

       -a, --applyall
              apply all available patches.

EXAMPLES

   Create a new patch to be applied after an existing patch.
       To create a new patch, to be applied after an existing patch 90_ctrlkeyfix:

       $ dpatch-edit-patch patch 95_newupstreamfix 90_ctrlkeyfix
       dpatch-edit-patch: * debian/patches/95_newupstreamfix.dpatch does not exist, it will be created as a new dpatch.
       dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
        ...
       dpatch-edit-patch: * Applying patches
       dpatch-edit-patch: ** Applying patch 90_ctrlkeyfix ... applied cleanly.
       dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
        ...
       $ editor files
       $ exit 0
       dpatch-edit-patch: * Creating new patch debian/patches/95_newupstreamfix.dpatch
       dpatch-edit-patch: Warning: debian/patches/00template does not exist, using hardcoded default.
       dpatch-edit-patch: debian/patches/95_newupstreamfix.dpatch created.

   Create a new patch not depending on existing patches
       To  create  a  new  patch, intended to be applied before any other patches (or a new patch
       which doesn't require other patches to be applied first):

       $ dpatch-edit-patch 10_debianstrings
       dpatch-edit-patch: * debian/patches/10_debianstrings.dpatch does not exist, it will be created as a new dpatch.
       dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
        ...
       dpatch-edit-patch: Warning: * No base-patch supplied, not applying any patches.
       dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
        ...
       $ editor files
       $ exit 0
        ...
       dpatch-edit-patch: * Creating new patch debian/patches/10_debianstrings.dpatch
       dpatch-edit-patch: Warning: debian/patches/00template does not exist, using hardcoded default.
       dpatch-edit-patch: debian/patches/10_debianstrings.dpatch created.

   Edit an existing patch:
       $ dpatch-edit-patch 10_debianstrings
       dpatch-edit-patch: * debian/patches/10_debianstrings.dpatch exists, this patch will be updated.
       dpatch-edit-patch: * Cleaning /home/david/temp/sopwith-1.6.0
        ...
       dpatch-edit-patch: * Applying patches
       dpatch-edit-patch: * Copying /home/david/temp/sopwith-1.6.0 to work directory.
       dpatch-edit-patch: * Applying current 10_debianstrings for editing.
        ...
       $ editor files
       $ exit 0
       dpatch-edit-patch: Updating patch debian/patches/10_debianstrings.dpatch
       dpatch-edit-patch: @DPATCH@ tag found, preserving dpatch header.
       dpatch-edit-patch: debian/patches/10_debianstrings.dpatch updated.

NOTES

       dpatch-edit-patch uses the DEBFULLNAME environment variable as the author's name. If it is
       unset, the author name will be left blank.

       dpatch-edit-patch  determines  the  author's  email  address  for  new  patches  using the
       following algorithm:
       1) Should the DEBEMAIL environment variable exist, it is always used.
       2) If the EMAIL environment variable exists, it will be used when DEBEMAIL does not exist.
       3) Should neither of the first two attempts succeed, the email will be  constructed  using
       the  login name of the user running dpatch-edit-patch combined with the output of hostname
       -f.

       When dpatch-edit-patch sets up a reference or a working  directory,  it  dereferences  all
       symlinks in the source. That allows relative links to continue working, and allows changes
       only to a single file and not to  the  linked  file  and  the  link  target.  If  you  use
       dpatch-edit-patch  on source trees that have symbolic links, you might end up with a patch
       that is unapplyable to the original tree.

FILES

       debian/patches/00dpatch.conf, ~/.dpatch.conf.

SEE ALSO

       dpatch(1), dpatch(7), dpatch.make(7), dpatch-list-patch(1), dpatch-convert-diffgz(1)

       Files in /usr/share/doc/dpatch/

AUTHOR

       This manual page was written by David B Harris <david@eelf.ddts.net> and modified  in  the
       course    of    development    by   Gergely   Nagy   <algernon@debian.org>,   Marc   Haber
       <mh+debian-packages@zugschlus.de>,  Stefano  Zacchiroli  <zack@debian.org>,  and   Junichi
       Uekawa <dancer@debian.org>.