GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       wiggle - apply rejected patches and perform word-wise diffs

SYNOPSIS

       wiggle [function] [options] file [files]

DESCRIPTION

       The  main function of wiggle is to apply a patch to a file in a similar
       manner to the patch(1) program.

       The distinctive difference of wiggle is that it will attempt to apply a
       patch  even  if the "before" part of the patch doesn't match the target
       file perfectly.  This is achieved by breaking the file and  patch  into
       words and finding the best alignment of words in the file with words in
       the patch.  Once this alignment has been found, any differences  (word-
       wise) in the patch are applied to the file as best as possible.

       Also, wiggle will (in some cases) detect changes that have already been
       applied, and will ignore them.

       wiggle ensures that every change in the patch is applied to the  target
       file  somehow.   If a particular change cannot be made in the file, the
       file is annotated to show where the change should be made in a  similar
       way  to  the  merge(1)  program  with  the  -A option.  Each annotation
       contains 3 components: a portion of the original file where the  change
       should  be  applied,  a  portion  of the patch that couldn't be matched
       precisely in the file, and the text that should replace that portion of
       the  patch.   These  are  separated  by  lines  containing  precisely 7
       identical characters, either '<', '|', '=', or '>',  possibly  followed
       by a descriptive word. So
            <<<<<<< found
            Some portion of the original file
            ||||||| expected
            text to replace
            =======
            text to replace it with
            >>>>>>> replacement
       indicates that "text to replace" should be replaced by "text to replace
       it with" somewhere in the portion of the original file.  However wiggle
       was not able to find a place to make this change.

       wiggle  can  also  produce conflict reports showing only the words that
       are involved rather than showing whole lines.  In this case the  output
       looks like:
            <<<---original|||old===new--->>>

       One  possible  usage of wiggle is to run patch to apply some patch, and
       to collect a list of rejects by  monitoring  the  error  messages  from
       patch.  Then for each file for which a reject was found, run
            wiggle --replace originalfile originalfile.rej

       Finally each file must be examined to resolve any unresolved conflicts,
       and to make sure the applied patch is semantically correct.

       Alternately, the original patch file can be fed to the browse mode as
            wiggle -B < patchfile

       This will allow the changes and conflicts to be inspected and, to  some
       extent, modified; and then the results can be saved.

   OPTIONS
       The  following  options  are  understood  by wiggle.  Some of these are
       explained in more detail in the  following  sections  on  MERGE,  DIFF,
       EXTRACT, and BROWSE.

       -m, --merge
              Select the "merge" function.  This is the default function.

       -d, --diff
              Select  the  "diff"  function.   This  displays  the differences
              between files.  This can be given after --browse (see below)  in
              which  case  a  patch or diff of two files can be viewed without
              the originals.

       -x, --extract
              Select the "extract" function.  This extracts one  branch  of  a
              patch or merge file.

       -B, --browse
              Select  the  "browse"  function.  This is similar to "merge" (or
              "diff") only with a  different  presentation.   Instead  of  the
              result  simply  being  sent  to standard output, it is presented
              using an ncurses-based GUI so that each hunk of the patch can be
              examined  to  understand  what conflicts where involved and what
              needed to be ignored in order of the patch to be wiggled  in  to
              place.

       -w, --words
              Request  that all operations and display be word based.  This is
              the default for the "diff" function.

       -l, --lines
              Request that all operations and display be line based.

       -b, --ignore-blanks
              De-emphasise  white  space  (space,   tab,   and   newline)   is
              determining differences and changes.

              Normally white space is treated like a word which can be matched
              or changed by a patch.  When this flag is in force, white  space
              serves  only  as  a  separator  between  other  words and is not
              matched itself.  The effect of  this  is  that  changes  in  the
              amount of white space are not treated as significant.

              To  be  precise,  any white space is combined with the preceding
              word or, in the case of  leading  space  on  a  line,  with  the
              following  word.   However it is not involved in any comparisons
              of that word.  If a patch deletes a  word,  the  attached  white
              space  is deleted as well.  If a patch adds a word, the attached
              white space is added as well.

              An empty line, or one that contains only blanks, will be treated
              as a single word that will match any other blank line, no matter
              how many spaces it has.

              -b has no effect in --line mode.

       -p, --patch
              Treat the last named file as a patch instead  of  a  file  (with
              --diff)  or  a  merge  (--extract).  In merge or browse mode, -p
              requires there be exactly one file which is a  patch  and  which
              can  contain  patches to multiple files.  The patches are merged
              into each file.  When used in merge mode,  this  usage  requires
              the  --replace  option  as  writing  lots  of  merged  files  to
              standard-out is impractical.

              When processing a multi-file patch, -p  can  be  followed  by  a
              numeric argument indicating how many file name components should
              be stripped from files named in the patch file.  If  no  numeric
              argument  is  given,  wiggle  will  deduce an appropriate number
              based what files are present in the filesystem.

       -r, --replace
              Normally the merged output is written to standard-output.   With
              --replace,  the original file is replaced with the merge output.
              In browse  mode,  this  instructs  wiggle  to  always  save  the
              resulting merge when exiting.

       -o, --output=
              Rather  than  writing  the  result  to  stdout or to replace the
              original file, this requests that the output be written  to  the
              given  file.   This  is only meaningful with --merge or --browse
              when given a single merge to browse.

              This option overrides -r.

       -R, --reverse
              When  used  with  the  diff  function,  swap  the  files  before
              calculating the differences.  When used with the merge or browse
              functions, wiggle attempts to revert changes rather  than  apply
              them.

       -i, --no-ignore
              Normally wiggle will ignore changes in the patch which appear to
              already have been applied in the original.  With this flag those
              changes are reported as conflicts rather than being ignored.

       -W, --show-wiggles
              When used with --merge, conflicts that can be wiggled into place
              are reported as conflicts with an extra stanza which shows  what
              the  result  would be if this flag had not been used.  The extra
              stanza is introduce with  a  line  containing  7  ampersand  (&)
              characters thus:
                   <<<<<<< found
                   Some portion of the original file
                   ||||||| expected
                   text to replace
                   =======
                   text to replace it with
                   &&&&&&& resolution
                   Text that would result from a successful wiggle
                   >>>>>>> replacement

       --report-wiggles
              If  a  merge  is  successful  in  applying  all changes, it will
              normally exit with a success status (0), only reporting  failure
              (1)   if   a   conflict   occurred   and  was  annotated.   With
              --report-wiggles wiggle will also report failure if any  changes
              had  to  be  wiggled in.  This can be useful when wiggle is used
              for automatic merges as with git.  If any  wiggles  happen,  git
              will  report  the  failure,  and  the results can be examined to
              confirm they are acceptable.

       -h, --help
              Print a simple help message.  If given after one of the function
              selectors  (--merge,  --diff, --extract, --browse) help specific
              to that function is displayed.

       -V, --version
              Display the version number of wiggle.

       -v, --verbose
              Enable verbose mode.  Currently this makes no difference.

       -q, --quiet
              Enable quiet mode.  This suppresses the message from  the  merge
              function when there are unresolvable conflicts.

   WORDS
       wiggle  can  divide  a  text  into  lines or words when performing it's
       tasks.  A line is  simply  a  string  of  characters  terminated  by  a
       newline.  A word is either a maximal contiguous string of alphanumerics
       (including underscore), a maximal contiguous string  of  space  or  tab
       characters, or any other single character.

   MERGE
       The merge function modifies a given text by finding all changes between
       two other texts and imposing those changes on the given text.

       Normally wiggle focuses on which words have changed so as  to  maximise
       the  possibility  of  finding  a  good  match in the given text for the
       context of a given change.  However it can consider  only  whole  lines
       instead.

       wiggle  extracts the three texts that it needs from files listed on the
       command line.  Either 1, 2, or 3 files may be listed, and  any  one  of
       them may be a lone hyphen signifying standard-input.

       If  one  file  is  given  and the -p option is not present, the file is
       treated as a merge file, i.e. the output of  "merge  -A"  or  "wiggle".
       Such  a  file implicitly contains three streams and these are extracted
       and compared.

       If two files are given, then the  first  simply  contains  the  primary
       text,  and  the  second  is  treated  as  a  patch  file (the output of
       "diff -u" or "diff -c", or a ".rej" file from patch) and the two  other
       texts are extracted from that.

       If  one  file is given together with the -p option, the file is treated
       as a patch file containing the names of the files that it patches.   In
       this  case  multiple  merge  operations  can  happen and each takes one
       stream from a file named in the patch, and the other two from the patch
       itself.   The  --replace option is required and the results are written
       back to the target files.

       Finally if three files are listed, they are taken to contain the  given
       text and the two other texts, in order.

       Normally the result of the merge is written to standard-output.  If the
       -r flag is given, the output is written to a file  which  replaces  the
       original  given file. In this case the original file is renamed to have
       a .porig suffix (for "patched original" which makes sense if you  first
       use  patch  to apply a patch, and then use wiggle to wiggle the rejects
       in).

       Further if the -o option is given with a file name, the output will  be
       written to that file.  In this case no backup is created.

       If no errors occur (such as file access errors) wiggle will exit with a
       status of 0 if all changes were successfully merged, and with  an  exit
       status  of  1  and  a  brief  message if any changes could not be fully
       merged and were instead inserted as  annotations.   However  if  either
       --report-wiggles or --show-wiggles options were given, wiggle will also
       exist with status of 1 if any changes had to be wiggled in even  though
       this was successful.

       The merge function can operate in three different modes with respect to
       lines or words.

       With the --lines option, whole lines are compared and any conflicts are
       reported as whole lines that need to be replaced.

       With  the  --words  option,  individual  words  are  compared  and  any
       conflicts are reported just covering the words affected.  This uses the
       <<<|||===>>>  conflict format.

       Without   either   of  these  options,  a  hybrid  approach  is  taken.
       Individual words are compared and merged, but when a conflict is  found
       the whole surrounding line is reported as being in conflict.

       wiggle  will  ensure  that  every change between the two other texts is
       reflected in the result of the merge somehow.  There are four different
       ways that a change can be reflected.

       1      If  a  change converts A to B and A is found at a suitable place
              in the original file, it is replaced with B.  This includes  the
              possibility that B is empty, but not that A is empty.

       2      If  a  change  is  found  which  simply  adds  B  and  the  text
              immediately preceding and  following  the  insertion  are  found
              adjacent  in  the  original  file in a suitable place, then B is
              inserted between those adjacent texts.

       3      If a change is found which changes  A  to  B  and  this  appears
              (based  on  context) to align with B in the original, then it is
              assumed that this change  has  already  been  applied,  and  the
              change  is ignored.  When this happens, a message reflecting the
              number  of  ignored  changes  is  printed   by   wiggle.    This
              optimisation can be suppressed with the -i flag.

       4      If  a  change  is  found  that  does  not  fit  any of the above
              possibilities, then a conflict is reported as described earlier.

   DIFF
       The diff function is provided primarily  to  allow  inspection  of  the
       alignments  that  wiggle  calculated between texts and that it uses for
       performing a merge.

       The output of the diff function is similar to  the  unified  output  of
       diff.   However  while  diff  does  not output long stretches of common
       text, wiggle's diff mode outputs everything.

       When calculating a word-based alignment (the default), wiggle may  need
       to  show these word-based differences.  This is done using an extension
       to the unified-diff format.  If a line starts with a vertical bar, then
       it may contain sections surrounded by special multi-character brackets.
       The brackets "<<<++" and "++>>>" surround added text while "<<<--"  and
       "-->>>" surround removed text.

       wiggle can be given the two texts to compare in one of three ways.

       If  only  one  file is given, then it is treated as a patch and the two
       branches of that patch are compared.  This effectively allows  a  patch
       to be refined from a line-based patch to a word-based patch.

       If  two  files  are  given, then they are normally assumed to be simple
       texts to be compared.

       If two files are given along with the --patch option, then  the  second
       file  is  assumed  to  be a patch and either the first (with -1) or the
       second (with -2) branch is extracted and compared with  text  found  in
       the first file.

       This  last  option  causes  wiggle  to apply a "best-fit" algorithm for
       aligning patch hunks with the file before  computing  the  differences.
       This  algorithm is used when merging a patch with a file, and its value
       can be seen by comparing the difference  produced  this  way  with  the
       difference  produced  by  first extracting one branch of a patch into a
       file, and then computing the difference of  that  file  with  the  main
       file.

   EXTRACT
       The   extract   function   of   wiggle   simply  exposes  the  internal
       functionality for extracting one branch of a patch or a merge file.

       Precisely one file should be given, and it will  be  assumed  to  be  a
       merge file unless --patch is given, in which case a patch is assumed.

       The  choice  of  branch  in made by providing one of -1, -2, or -3 with
       obvious meanings.

   BROWSE
       The browse function of wiggle presents the result of a merge  or  (with
       -d)  a  diff in a text-based GUI that can be navigated using keystrokes
       similar to vi(1) or emacs(1).

       The browser allows each of the two  or   three  streams  to  be  viewed
       individually  with  colours used to highlight different sorts of text -
       green for added text, red for deleted text etc.  It can also  show  the
       patch  by  itself,  the  full result of the merge, or the merge and the
       patch side-by-side.

       The browser provides a number of context-sensitive help pages which can
       be accessed by typing '?'

       The top right of the GUI will report the type of text under the cursor,
       which is also indicated  by  the  colour  of  the  text.   Options  are
       Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and Conflict.
       If the meanings of these are clear  a  little  experimentations  should
       help.

       A  limited  amount  of  editing  is  permitted  while  in  browse mode.
       Currently text that is unwanted can be discarded  with  x.   This  will
       convert  a Conflict or Change to Unchanged, and an Unmatched to Changed
       (which effectively changes it to the empty string).  Similarly  a  text
       can  be  marked  as  wanted  with  c.   This will convert a Conflict or
       Extraneous to Changed.  Using  the  same  key  again  will  revert  the
       change.

       Finally, the uppercase X will revert all changes on the current line.

       To  make  more  sweeping  changes  you  can use v which runs an editor,
       preferring $VISUAL or $EDITOR if they are set in the environment.

       If you make any changes, then wiggle will ask you if you want  to  save
       the changes, even if --replace was not given.

WARNING

       Caution  should always be exercised when applying a rejected patch with
       wiggle.  When patch rejects a patch, it does  so  for  a  good  reason.
       Even though wiggle may be able to find a believable place to apply each
       textual change, there is no guarantee that the result is correct in any
       semantic  sense.  The result should always be inspected to make sure it
       is correct.

EXAMPLES

         wiggle --replace file file.rej
       This is the normal usage  of  wiggle  and  will  take  any  changes  in
       file.rej that patch could not apply, and merge them into file.

         wiggle -dp1 file file.rej
       This  will  perform  a  word-wise  comparison  between the file and the
       before branch of the diff in  file.rej  and  display  the  differences.
       This allows you to see where a given patch would apply.

          wiggle --merge --help
       Get help about the merge function of wiggle.

          wiggle --browse --patch update.patch
       Parse  the  update.patch file for patches and present a list of patched
       files which can be browsed to examine each patch in detail.

       wiggle can be integrated with git so that it is  used  as  the  default
       merge tool and diff tool.  This can be achieved by adding the following
       lines to .gitconfig in the user's home directory.
           [merge "wiggle"]
                name = "Wiggle flexible merging"
                driver = wiggle -o %A %A %O %B
                recursive = binary
           [merge]
                tool = wiggle
           [mergetool "wiggle"]
                cmd = wiggle -B -o $MERGED $LOCAL $BASE $REMOTE
           [difftool "wiggle"]
                cmd = wiggle -Bd $LOCAL $REMOTE
       This will make git mergetool and git difftool use wiggle.

       If you want  git  to  always  use  wiggle  for  merges  (which  may  be
       dangerous), you can add
           * merge=wiggle
       to      an      appropriate      gitattributes     file     such     as
       $HOME/.config/git/attributes.

QUOTE

       The name of wiggle was inspired by the following quote.

       The problem I find is that I often want to take
         (file1+patch) -> file2,
       when I don't have file1.  But merge tools want to take
         (file1|file2) -> file3.
       I haven't seen a graphical tool which helps you to wiggle a patch
       into a file.
       -- Andrew Morton - 2002

SHORTCOMINGS

       -      wiggle cannot read the  extended  unified-diff  output  that  it
              produces for --diff --words.

       -      wiggle  cannot read the word-based merge format that it produces
              for --merge --words.

       -      wiggle does not understand unicode and so will  treat  all  non-
              ASCII  characters  much  the  same as it treats punctuation - it
              will treat each one as a separate word.  The  browser  will  not
              display non-ASCII characters properly.

AUTHOR

       Neil Brown at Computer Science and Engineering at The University of New
       South Wales, Sydney, Australia; and later at  SUSE,  still  in  Sydney,
       Australia.

SEE ALSO

       patch(1),   diff(1),   merge(1),   wdiff(1),  diff3(1),  git-config(1),
       gitattributes(5).



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.132 seconds. Last modified: November 04 2018 12:49:43.