unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

DPATCH-EDIT-PATCH(1)          dpatch users manual         DPATCH-EDIT-PATCH(1)



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

       dpatch-cowdancer-patch - a variation which uses hardlinks and cowdancer


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

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


DESCRIPTION
       This  manual  documents  the  dpatch-edit-patch command and dpatch-cow-
       dancer-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.

       dpatch-cowdancer-patch is a variation of dpatch-edit-patch which  tries
       to use hardlinks and cowdancer.


OPTIONS
       dpatch-edit-patch  and  dpatch-cowdancer-patch  take two forms of argu-
       ments; 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  work-
              ing  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.

              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 vari-
       ables.      Configuration      variables      are       read       from
       debian/patches/00dpatch.conf and ~/.dpatch.conf.

       -s, --sourcedir=value
              Directory containing unpacked Debian source package.  Configura-
              tion 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. Configu-
              ration variable conf_clean (~/.dpatch.conf),  Environment  vari-
              able 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 or excluding the tarball
              name. If the given path is only a  directory,  dpatch-edit-patch
              tries  to determine the .orig.tar.gz tarball name from dpkg-par-
              sechangelog. Otherwise it will unpack and use the given tarball.
              If    no    value   is   given,   dpatch-edit-patch   will   use
              dpatch-get-origtargz  or  the  hook   script   pointed   to   by
              conf_getorigtargz   (~/.dpatch.conf)   or  DPEP_GETORIGTARGZ  to
              obtain the upstream tarball. The hook script should be  callable
              identically  to  dpatch-get-origtargz.  Configuration variables:
              conf_debianonly  (debian/patches/00dpatch.conf)  and  conf_orig-
              targz  (~/.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 direc-
              tories.      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,  environ-
              ment 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 vari-
              able   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),  environ-
              ment 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.

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

       --cowcmd=cow-shell
              The  command used as shell for dpatch-cowdancer-patch.  configu-
              ration variable conf_cowcmd, environment variable DPEP_COWCMD.

       -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_ctr-
       lkeyfix:

       $ 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  determines  the  author  for  new patches using this
       algorithm:
       1) Should the DEBFULLNAME environment variable exist, it is used.
       2) An attempt is made to retrieve  the  information  via  the  system's
       passwd database
       3)  If the above two attempts fail, the author's name will be blank and
       only an email address will be substituted.

       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 DEBE-
       MAIL 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-get-origtargz(1), dpatch-convert-diffgz(1)

       Files in /usr/share/doc/dpatch/


AUTHOR
       This manual page was written by David  B  Harris  <davidATeelf.net>
       and  modified  in  the  course  of  development by Gergely Nagy <alger-
       nonATdebian.org>, Marc Haber <mh+debian-packagesATzugschlus.de>,  Stefano
       Zacchiroli <zackATdebian.org>, and Junichi Uekawa <dancerATdebian.org>.





DPATCH                            21 Jun 2007             DPATCH-EDIT-PATCH(1)