WIGGLE(1)

WIGGLE(1) — General Commands Manual 💅

NAME 🎀

wiggle — apply rejected patches and perform word-wise diffs ✨

SYNOPSIS 🌸

wiggle [function] [options] file [files]

DESCRIPTION 🦋

Okay so the main character function of wiggle is to apply a patch to a file, kinda like what patch(1) does. 💅

But here's the distinctive difference, bestie: wiggle will still try to apply a patch even if the "before" part of the patch doesn't match the target file perfectly. No cap. It does this by breaking the file and patch into words and finding the best alignment of words in the file with words in the patch. Once that alignment is found, any differences (word-wise) in the patch get 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. Lowkey iconic.

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, similar 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

This 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. Periodt. 💖

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. ✨
• --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 automatically 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 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. 💖
• --no-backup — Normally when an original file is replaced with the merged result, 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 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. 🦋
• --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 takes 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 (&) 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. ✨

Okay so boom, continuing right where we left off, bestie 💖

If you hand it two files, the first one is just the primary text, and the second one gets treated as a patch file — so like, the output of diff -u or diff -c, or a .rej file from patch — and the other two texts get extracted from that patch. Cute, right? ✨

If you give it one file together with the -p option, that file is treated as a patch file that literally contains the names of the files it patches. In that case, multiple merge operations can happen at once, and each one takes one stream from a file named inside the patch, and the other two streams from the patch itself. The --replace option is required here, and the results get written back to the target files. No take-backs 💅

And finally, if you list three files, they're taken to contain the given text plus the two other texts, in order. That's it, that's the trio 🌸

---

Normally the result of the merge goes straight to standard-output. If you pass the -r flag though, the output gets written to a file that replaces the original given file. In that case the original file normally gets renamed with a .porig suffix (that's "patched original" — makes total sense if you first use patch to apply a patch, and then use wiggle to wiggle the rejects in 🫶). You can suppress that with the --no-backup uption. (yes bestie that's literally how it's spelled in the original, we don't touch it 🙈)

Also, if you give the -o option with a file name, the output goes to that file. And in that case, no backup gets created. Iconic, honestly.

---

Now for exit statuses, the moment you've been waiting for 👑

If no errors occur (like file access errors or whatever), wiggle exits with a status of 0 if all changes were successfully merged. It exits with a status of 1 and a brief message if any changes could not be fully merged and were instead inserted as annotations. BUT — and this is the plot twist — if either --report-wiggles or --show-wiggles was given, then wiggle also exits with status 1 if any changes had to be wiggled in, even though that was successful. Slay but noted 💀

---

The merge function can operate in three different modes when it comes to lines vs 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 covering just the words affected. This uses the <<<|||===>>> conflict format.
• Without either of those options, it takes a hybrid approach: individual words are compared and merged, but when a conflict shows up, the whole surrounding line gets reported as being in conflict.

---

wiggle will make sure that every change between the two other texts is reflected in the result of the merge somehow. There are four different ways 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 gets replaced with B. This includes the possibility that B is empty — but not that A is empty.
2. If a change is found that 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 gets 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's assumed that this change has already been applied, and the change is ignored. When this happens, a message reflecting the number of ignored changes gets printed by wiggle. This optimisation can be suppressed with the -i flag.
4. If a change is found that doesn't fit any of the above possibilities, then a conflict is reported, as described earlier.

---

🔍 DIFF 🔍

The diff function is there primarily so you can inspect the alignments that wiggle calculated between texts, and that it uses for performing a merge. Very "let me show you my work" of it ✨

The output of the diff function is similar to the unified output of diff. However — while diff doesn't output long stretches of common text, wiggle's diff mode outputs everything. No secrets here, bestie.

When calculating a word-based alignment (which is the default), wiggle may need to show these word-based differences. It does this 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. Little bracket besties holding hands 🫶

You can give wiggle the two texts to compare in one of three ways:

• If only one file is given, then it's treated as a patch, and the two branches of that patch are compared. This effectively lets a patch be refined from a line-based patch into a word-based patch. Glow-up arc 💅
• If two files are given, then they're 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.

That last option makes wiggle 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 you can see its value 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. Yeah, it's giving "trust the process" 😭

---

🧲 EXTRACT 🧲

The extract function of wiggle simply exposes the internal functionality for extracting one branch of a patch or a merge file. It's like the backstage pass of the whole operation 🎀

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

The choice of branch is made by providing one of -1, -2, or -3, with obvious meanings. Pick your fighter 🌈

---

🖥️ BROWSE 🖥️

The browse function of wiggle presents the result of a merge — or, with -d, a diff — in a text-based GUI that you can navigate with keystrokes similar to vi(1) or emacs(1). Main character energy, but make it terminal 👑

The browser lets each of the two or three streams 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. A whole aesthetic ✨

The browser provides a number of context-sensitive help pages which you can access by typing '?'.

The top right of the GUI reports the type of text under the cursor, which is also indicated by the colour of the text. The options are Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and Conflict. If the meanings of these are clear, a little experimentation should help. Vibes-based learning fr fr 🌸

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. Undo culture, we love to see it 💜

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're set in the environment. Respect the environment variables, bestie 🌈

If you make any changes, then wiggle will ask you if you want to save the changes, even if --replace was not given. It just wants to be sure 🥺

---

⚠️ 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's correct.

Bestie, I am so serious about this one. Believable ≠ correct. Always look at the result. No cap. 🚨

---

🌟 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. The classic 💅

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. Detective mode 🔍

wiggle --merge --help

Get help about the merge function of wiggle. Ask for directions, it's fine 🫶

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. So organised of it ✨

---

wiggle can be integrated with git so that it's used as the default merge tool and diff tool. You can achieve this 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. Glow-up for your whole workflow 💖

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

Honestly? A visionary. 🌟

---

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

Yeah bestie, it can't read its own homework in a couple of cases. We still love it. 💀

---

👑 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. Legend behaviour, fr fr 🎀

---

🔗 SEE ALSO 🔗

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

---

And that's a wrap on WIGGLE(1) — this whole page is from v1.3, so go forth and wiggle those rejects into place, bestie. Inspect your results, respect the warning, and stay iconic 💅✨🦋