Provided by: dpatch_2.0.34ubuntu1_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>.