Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WIGGLE(1)		    General Commands Manual		     WIGGLE(1)

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 con-
       tains 3 components: a portion of	the original  file  where  the	change
       should be applied, a portion of the patch that couldn't be matched pre-
       cisely in the file, and the text	that should replace  that  portion  of
       the patch.  These are separated by lines	containing precisely 7 identi-
       cal 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 ex-
       plained in more detail in the following sections	on  MERGE,  DIFF,  EX-
       TRACT, and BROWSE.

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

       -d, --diff
	      Select  the  "diff" function.  This displays the differences be-
	      tween 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  re-
	      sult simply being	sent to	standard output, it is presented using
	      an ncurses-based GUI so that each	hunk of	the patch can be exam-
	      ined 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.

       --non-space
	      Request  that  words be defined as sequences of non-white-space.
	      Without this flag	words are sequences of alphanumerics or	single
	      non-white-space  characters.   This flag is enabled by automati-
	      cally enabled if wiggle needs to compare two  files  which  both
	      have more	than 50,000 words.

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

       -b, --ignore-blanks
	      De-emphasise  white space	(space,	tab, and newline) is determin-
	      ing 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 fol-
	      lowing 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 re-
	      quires  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 nu-
	      meric 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 result-
	      ing merge	when exiting.

       --no-backup
	      Normally when an original	file is	replaced with the  merged  re-
	      sult, that file is renamed to have a ".porig" extension, so that
	      it is preserved.	If you don't want to keep  the	original,  use
	      this option to suppress the backup.

       -o, --output=
	      Rather than writing the result to	stdout or to replace the orig-
	      inal 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	calcu-
	      lating  the  differences.	  When	used  with the merge or	browse
	      functions, wiggle	attempts to revert changes rather  than	 apply
	      them.

       --shortest
	      If  the  files being compared are	large, it can take a long time
	      to isolate the differences.  Normally wiggle  will  give	up  on
	      perfection  if  a	step take more than 20msec.  To	over-ride this
	      and always find the shortest edit-distance  between  two	files,
	      use the --shortest option.

       -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 (&) char-
	      acters 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 nor-
	      mally 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	 fail-
	      ure, and the results can be examined to confirm they are accept-
	      able.

       -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  new-
       line.   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 con-
       text of a given change.	However	it can consider	only whole  lines  in-
       stead.

       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 will normally be
       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).	This can be suppressed	with  the  --no-backup
       uption.

       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  con-
       flicts  are  reported  just covering the	words affected.	 This uses the
       <<<|||===>>>  conflict format.

       Without either of these options,	a hybrid approach is taken.   Individ-
       ual  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 re-
       flected	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  immedi-
	      ately  preceding	and following the insertion are	found adjacent
	      in the original file in a	suitable place,	then B is inserted be-
	      tween 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 optimisa-
	      tion can be suppressed with the -i flag.

       4      If a change is found that	does not fit any of the	 above	possi-
	      bilities,	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 dif-
       ference 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 functional-
       ity 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 ob-
       vious 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 indi-
       vidually	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  Un-
       changed,	 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.  Cur-
       rently text that	is unwanted can	be discarded with x.  This  will  con-
       vert  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	Extra-
       neous 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,  pre-
       ferring $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  be-
       fore  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 danger-
       ous), you can add
	   * merge=wiggle
       to an appropriate  gitattributes	 file  such  as	 $HOME/.config/git/at-
       tributes.

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 pro-
	      duces 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),	gitat-
       tributes(5).

v1.3								     WIGGLE(1)

NAME | SYNOPSIS | DESCRIPTION | WARNING | EXAMPLES | QUOTE | SHORTCOMINGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wiggle&sektion=1&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help