1WIGGLE(1)                   General Commands Manual                  WIGGLE(1)
2
3
4

NAME

6       wiggle - apply rejected patches and perform word-wise diffs
7

SYNOPSIS

9       wiggle [function] [options] file [files]
10

DESCRIPTION

12       The  main function of wiggle is to apply a patch to a file in a similar
13       manner to the patch(1) program.
14
15       The distinctive difference of wiggle is that it will attempt to apply a
16       patch  even  if the "before" part of the patch doesn't match the target
17       file perfectly.  This is achieved by breaking the file and  patch  into
18       words and finding the best alignment of words in the file with words in
19       the patch.  Once this alignment has been found, any differences  (word-
20       wise) in the patch are applied to the file as best as possible.
21
22       Also, wiggle will (in some cases) detect changes that have already been
23       applied, and will ignore them.
24
25       wiggle ensures that every change in the patch is applied to the  target
26       file  somehow.   If a particular change cannot be made in the file, the
27       file is annotated to show where the change should be made in a  similar
28       way  to  the merge(1) program with the -A option.  Each annotation con‐
29       tains 3 components: a portion of the original  file  where  the  change
30       should be applied, a portion of the patch that couldn't be matched pre‐
31       cisely in the file, and the text that should replace  that  portion  of
32       the patch.  These are separated by lines containing precisely 7 identi‐
33       cal characters, either '<', '|', '=', or '>', possibly  followed  by  a
34       descriptive word. So
35            <<<<<<< found
36            Some portion of the original file
37            ||||||| expected
38            text to replace
39            =======
40            text to replace it with
41            >>>>>>> replacement
42       indicates that "text to replace" should be replaced by "text to replace
43       it with" somewhere in the portion of the original file.  However wiggle
44       was not able to find a place to make this change.
45
46       wiggle  can  also  produce conflict reports showing only the words that
47       are involved rather than showing whole lines.  In this case the  output
48       looks like:
49            <<<---original|||old===new--->>>
50
51       One  possible  usage of wiggle is to run patch to apply some patch, and
52       to collect a list of rejects by  monitoring  the  error  messages  from
53       patch.  Then for each file for which a reject was found, run
54            wiggle --replace originalfile originalfile.rej
55
56       Finally each file must be examined to resolve any unresolved conflicts,
57       and to make sure the applied patch is semantically correct.
58
59       Alternately, the original patch file can be fed to the browse mode as
60            wiggle -B < patchfile
61
62       This will allow the changes and conflicts to be inspected and, to  some
63       extent, modified; and then the results can be saved.
64
65   OPTIONS
66       The  following  options  are  understood  by wiggle.  Some of these are
67       explained in more detail in the  following  sections  on  MERGE,  DIFF,
68       EXTRACT, and BROWSE.
69
70       -m, --merge
71              Select the "merge" function.  This is the default function.
72
73       -d, --diff
74              Select  the  "diff"  function.   This  displays  the differences
75              between files.  This can be given after --browse (see below)  in
76              which  case  a  patch or diff of two files can be viewed without
77              the originals.
78
79       -x, --extract
80              Select the "extract" function.  This extracts one  branch  of  a
81              patch or merge file.
82
83       -B, --browse
84              Select  the  "browse"  function.  This is similar to "merge" (or
85              "diff") only with a  different  presentation.   Instead  of  the
86              result  simply  being  sent  to standard output, it is presented
87              using an ncurses-based GUI so that each hunk of the patch can be
88              examined  to  understand  what conflicts where involved and what
89              needed to be ignored in order of the patch to be wiggled  in  to
90              place.
91
92       -w, --words
93              Request  that all operations and display be word based.  This is
94              the default for the "diff" function.
95
96       -l, --lines
97              Request that all operations and display be line based.
98
99       -b, --ignore-blanks
100              De-emphasise white space (space, tab, and newline) is  determin‐
101              ing differences and changes.
102
103              Normally white space is treated like a word which can be matched
104              or changed by a patch.  When this flag is in force, white  space
105              serves  only  as  a  separator  between  other  words and is not
106              matched itself.  The effect of  this  is  that  changes  in  the
107              amount of white space are not treated as significant.
108
109              To  be  precise,  any white space is combined with the preceding
110              word or, in the case of leading space on a line, with  the  fol‐
111              lowing  word.   However it is not involved in any comparisons of
112              that word.  If a patch deletes a word, the attached white  space
113              is  deleted as well.  If a patch adds a word, the attached white
114              space is added as well.
115
116              An empty line, or one that contains only blanks, will be treated
117              as a single word that will match any other blank line, no matter
118              how many spaces it has.
119
120              -b has no effect in --line mode.
121
122       -p, --patch
123              Treat the last named file as a patch instead  of  a  file  (with
124              --diff)  or  a  merge  (--extract).  In merge or browse mode, -p
125              requires there be exactly one file which is a  patch  and  which
126              can  contain  patches to multiple files.  The patches are merged
127              into each file.  When used in merge mode,  this  usage  requires
128              the  --replace  option  as writing lots of merged files to stan‐
129              dard-out is impractical.
130
131              When processing a multi-file patch, -p  can  be  followed  by  a
132              numeric argument indicating how many file name components should
133              be stripped from files named in the patch file.  If  no  numeric
134              argument  is  given,  wiggle  will  deduce an appropriate number
135              based what files are present in the filesystem.
136
137       -r, --replace
138              Normally the merged output is written to standard-output.   With
139              --replace,  the original file is replaced with the merge output.
140              In browse mode, this instructs wiggle to always save the result‐
141              ing merge when exiting.
142
143       -o, --output=
144              Rather than writing the result to stdout or to replace the orig‐
145              inal file, this requests that the output be written to the given
146              file.   This  is  only  meaningful with --merge or --browse when
147              given a single merge to browse.
148
149              This option overrides -r.
150
151       -R, --reverse
152              When used with the diff function, swap the files  before  calcu‐
153              lating  the  differences.   When  used  with the merge or browse
154              functions, wiggle attempts to revert changes rather  than  apply
155              them.
156
157       -i, --no-ignore
158              Normally wiggle will ignore changes in the patch which appear to
159              already have been applied in the original.  With this flag those
160              changes are reported as conflicts rather than being ignored.
161
162       -W, --show-wiggles
163              When used with --merge, conflicts that can be wiggled into place
164              are reported as conflicts with an extra stanza which shows  what
165              the  result  would be if this flag had not been used.  The extra
166              stanza is introduce with a line containing 7 ampersand (&) char‐
167              acters thus:
168                   <<<<<<< found
169                   Some portion of the original file
170                   ||||||| expected
171                   text to replace
172                   =======
173                   text to replace it with
174                   &&&&&&& resolution
175                   Text that would result from a successful wiggle
176                   >>>>>>> replacement
177
178       --report-wiggles
179              If  a  merge is successful in applying all changes, it will nor‐
180              mally exit with a success status (0), only reporting failure (1)
181              if a conflict occurred and was annotated.  With --report-wiggles
182              wiggle will also report failure if any changes had to be wiggled
183              in.  This can be useful when wiggle is used for automatic merges
184              as with git.  If any wiggles happen, git will report  the  fail‐
185              ure, and the results can be examined to confirm they are accept‐
186              able.
187
188       -h, --help
189              Print a simple help message.  If given after one of the function
190              selectors  (--merge,  --diff, --extract, --browse) help specific
191              to that function is displayed.
192
193       -V, --version
194              Display the version number of wiggle.
195
196       -v, --verbose
197              Enable verbose mode.  Currently this makes no difference.
198
199       -q, --quiet
200              Enable quiet mode.  This suppresses the message from  the  merge
201              function when there are unresolvable conflicts.
202
203   WORDS
204       wiggle  can  divide  a  text  into  lines or words when performing it's
205       tasks.  A line is simply a string of characters terminated  by  a  new‐
206       line.   A  word  is either a maximal contiguous string of alphanumerics
207       (including underscore), a maximal contiguous string  of  space  or  tab
208       characters, or any other single character.
209
210   MERGE
211       The merge function modifies a given text by finding all changes between
212       two other texts and imposing those changes on the given text.
213
214       Normally wiggle focuses on which words have changed so as  to  maximise
215       the  possibility of finding a good match in the given text for the con‐
216       text of a given change.  However  it  can  consider  only  whole  lines
217       instead.
218
219       wiggle  extracts the three texts that it needs from files listed on the
220       command line.  Either 1, 2, or 3 files may be listed, and  any  one  of
221       them may be a lone hyphen signifying standard-input.
222
223       If  one  file  is  given  and the -p option is not present, the file is
224       treated as a merge file, i.e. the output of  "merge  -A"  or  "wiggle".
225       Such  a  file implicitly contains three streams and these are extracted
226       and compared.
227
228       If two files are given, then the  first  simply  contains  the  primary
229       text,  and  the  second  is  treated  as  a  patch  file (the output of
230       "diff -u" or "diff -c", or a ".rej" file from patch) and the two  other
231       texts are extracted from that.
232
233       If  one  file is given together with the -p option, the file is treated
234       as a patch file containing the names of the files that it patches.   In
235       this  case  multiple  merge  operations  can  happen and each takes one
236       stream from a file named in the patch, and the other two from the patch
237       itself.   The  --replace option is required and the results are written
238       back to the target files.
239
240       Finally if three files are listed, they are taken to contain the  given
241       text and the two other texts, in order.
242
243       Normally the result of the merge is written to standard-output.  If the
244       -r flag is given, the output is written to a file  which  replaces  the
245       original  given file. In this case the original file is renamed to have
246       a .porig suffix (for "patched original" which makes sense if you  first
247       use  patch  to apply a patch, and then use wiggle to wiggle the rejects
248       in).
249
250       Further if the -o option is given with a file name, the output will  be
251       written to that file.  In this case no backup is created.
252
253       If no errors occur (such as file access errors) wiggle will exit with a
254       status of 0 if all changes were successfully merged, and with  an  exit
255       status  of  1  and  a  brief  message if any changes could not be fully
256       merged and were instead inserted as  annotations.   However  if  either
257       --report-wiggles or --show-wiggles options were given, wiggle will also
258       exist with status of 1 if any changes had to be wiggled in even  though
259       this was successful.
260
261       The merge function can operate in three different modes with respect to
262       lines or words.
263
264       With the --lines option, whole lines are compared and any conflicts are
265       reported as whole lines that need to be replaced.
266
267       With  the  --words  option,  individual words are compared and any con‐
268       flicts are reported just covering the words affected.   This  uses  the
269       <<<|||===>>>  conflict format.
270
271       Without  either of these options, a hybrid approach is taken.  Individ‐
272       ual words are compared and merged, but when a  conflict  is  found  the
273       whole surrounding line is reported as being in conflict.
274
275       wiggle  will  ensure  that  every change between the two other texts is
276       reflected in the result of the merge somehow.  There are four different
277       ways that a change can be reflected.
278
279       1      If  a  change converts A to B and A is found at a suitable place
280              in the original file, it is replaced with B.  This includes  the
281              possibility that B is empty, but not that A is empty.
282
283       2      If  a  change  is found which simply adds B and the text immedi‐
284              ately preceding and following the insertion are  found  adjacent
285              in  the  original  file  in a suitable place, then B is inserted
286              between those adjacent texts.
287
288       3      If a change is found which changes  A  to  B  and  this  appears
289              (based  on  context) to align with B in the original, then it is
290              assumed that this change  has  already  been  applied,  and  the
291              change  is ignored.  When this happens, a message reflecting the
292              number of ignored changes is printed by wiggle.  This  optimisa‐
293              tion can be suppressed with the -i flag.
294
295       4      If  a  change is found that does not fit any of the above possi‐
296              bilities, then a conflict is reported as described earlier.
297
298   DIFF
299       The diff function is provided primarily  to  allow  inspection  of  the
300       alignments  that  wiggle  calculated between texts and that it uses for
301       performing a merge.
302
303       The output of the diff function is similar to  the  unified  output  of
304       diff.   However  while  diff  does  not output long stretches of common
305       text, wiggle's diff mode outputs everything.
306
307       When calculating a word-based alignment (the default), wiggle may  need
308       to  show these word-based differences.  This is done using an extension
309       to the unified-diff format.  If a line starts with a vertical bar, then
310       it may contain sections surrounded by special multi-character brackets.
311       The brackets "<<<++" and "++>>>" surround added text while "<<<--"  and
312       "-->>>" surround removed text.
313
314       wiggle can be given the two texts to compare in one of three ways.
315
316       If  only  one  file is given, then it is treated as a patch and the two
317       branches of that patch are compared.  This effectively allows  a  patch
318       to be refined from a line-based patch to a word-based patch.
319
320       If  two  files  are  given, then they are normally assumed to be simple
321       texts to be compared.
322
323       If two files are given along with the --patch option, then  the  second
324       file  is  assumed  to  be a patch and either the first (with -1) or the
325       second (with -2) branch is extracted and compared with  text  found  in
326       the first file.
327
328       This  last  option  causes  wiggle  to apply a "best-fit" algorithm for
329       aligning patch hunks with the file before  computing  the  differences.
330       This  algorithm is used when merging a patch with a file, and its value
331       can be seen by comparing the difference produced this way with the dif‐
332       ference produced by first extracting one branch of a patch into a file,
333       and then computing the difference of that file with the main file.
334
335   EXTRACT
336       The extract function of wiggle simply exposes the internal  functional‐
337       ity for extracting one branch of a patch or a merge file.
338
339       Precisely  one  file  should  be  given, and it will be assumed to be a
340       merge file unless --patch is given, in which case a patch is assumed.
341
342       The choice of branch in made by providing one of -1,  -2,  or  -3  with
343       obvious meanings.
344
345   BROWSE
346       The  browse  function of wiggle presents the result of a merge or (with
347       -d) a diff in a text-based GUI that can be navigated  using  keystrokes
348       similar to vi(1) or emacs(1).
349
350       The browser allows each of the two or  three streams to be viewed indi‐
351       vidually with colours used to highlight different sorts of text - green
352       for  added  text, red for deleted text etc.  It can also show the patch
353       by itself, the full result of the merge, or the  merge  and  the  patch
354       side-by-side.
355
356       The browser provides a number of context-sensitive help pages which can
357       be accessed by typing '?'
358
359       The top right of the GUI will report the type of text under the cursor,
360       which  is  also  indicated  by  the  colour  of  the text.  Options are
361       Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and Conflict.
362       If  the  meanings  of  these are clear a little experimentations should
363       help.
364
365       A limited amount of editing is permitted while in  browse  mode.   Cur‐
366       rently  text  that is unwanted can be discarded with x.  This will con‐
367       vert a Conflict or Change to Unchanged, and  an  Unmatched  to  Changed
368       (which  effectively  changes it to the empty string).  Similarly a text
369       can be marked as wanted with c.  This will convert a Conflict or Extra‐
370       neous to Changed.  Using the same key again will revert the change.
371
372       Finally, the uppercase X will revert all changes on the current line.
373
374       To  make more sweeping changes you can use v which runs an editor, pre‐
375       ferring $VISUAL or $EDITOR if they are set in the environment.
376
377       If you make any changes, then wiggle will ask you if you want  to  save
378       the changes, even if --replace was not given.
379

WARNING

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

EXAMPLES

389         wiggle --replace file file.rej
390       This is the normal usage  of  wiggle  and  will  take  any  changes  in
391       file.rej that patch could not apply, and merge them into file.
392
393         wiggle -dp1 file file.rej
394       This  will  perform  a  word-wise  comparison  between the file and the
395       before branch of the diff in  file.rej  and  display  the  differences.
396       This allows you to see where a given patch would apply.
397
398          wiggle --merge --help
399       Get help about the merge function of wiggle.
400
401          wiggle --browse --patch update.patch
402       Parse  the  update.patch file for patches and present a list of patched
403       files which can be browsed to examine each patch in detail.
404
405       wiggle can be integrated with git so that it is  used  as  the  default
406       merge tool and diff tool.  This can be achieved by adding the following
407       lines to .gitconfig in the user's home directory.
408           [merge "wiggle"]
409                name = "Wiggle flexible merging"
410                driver = wiggle -o %A %A %O %B
411                recursive = binary
412           [merge]
413                tool = wiggle
414           [mergetool "wiggle"]
415                cmd = wiggle -B -o $MERGED $LOCAL $BASE $REMOTE
416           [difftool "wiggle"]
417                cmd = wiggle -Bd $LOCAL $REMOTE
418       This will make git mergetool and git difftool use wiggle.
419
420       If you want git to always use wiggle for merges (which may  be  danger‐
421       ous), you can add
422           * merge=wiggle
423       to    an   appropriate   gitattributes   file   such   as   $HOME/.con‐
424       fig/git/attributes.
425

QUOTE

427       The name of wiggle was inspired by the following quote.
428
429       The problem I find is that I often want to take
430         (file1+patch) -> file2,
431       when I don't have file1.  But merge tools want to take
432         (file1|file2) -> file3.
433       I haven't seen a graphical tool which helps you to wiggle a patch
434       into a file.
435       -- Andrew Morton - 2002
436

SHORTCOMINGS

438       -      wiggle cannot read the extended unified-diff output that it pro‐
439              duces for --diff --words.
440
441       -      wiggle  cannot read the word-based merge format that it produces
442              for --merge --words.
443
444       -      wiggle does not understand unicode and so will  treat  all  non-
445              ASCII  characters  much  the  same as it treats punctuation - it
446              will treat each one as a separate word.  The  browser  will  not
447              display non-ASCII characters properly.
448

AUTHOR

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

SEE ALSO

455       patch(1),  diff(1), merge(1), wdiff(1), diff3(1), git-config(1), gitat‐
456       tributes(5).
457
458
459
460v1.1                                                                 WIGGLE(1)
Impressum