Provided by: wiggle_1.1-1_amd64 bug

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