Fossil SCM
Added a new doc distilling all the common methods for getting colorized diffs. Extracted its seed from the gitusers doc in part because it isn't Git-specific, and because there are more options to cover, sufficient to justify a separate doc.
Commit
7c99ebc5921446c9da30486fb315df0f3ed67e1e7e7e1e39683e17159ef84bf7
Parent
dd8d1a5809af15b…
4 files changed
+41
+6
-37
+1
+1
+41
| --- a/www/colordiff.md | ||
| +++ b/www/colordiff.md | ||
| @@ -0,0 +1,41 @@ | ||
| 1 | +# Colorized Diffs | |
| 2 | + | |
| 3 | +The oldest and most widely compatible method to get colorized diffs in | |
| 4 | +Fossil is to use its web UI: | |
| 5 | + | |
| 6 | + fossil ui --page '/vdiff?from=2024-04-01&to=trunk' | |
| 7 | + | |
| 8 | +That syntax is admittedly awkward, and it doesn’t work where “from” is | |
| 9 | +the current checkout. Fortunately, there are many other methods to get | |
| 10 | +colorized `diff` output from Fossil. | |
| 11 | + | |
| 12 | + | |
| 13 | +<a id="ui"></a> | |
| 14 | +## `fossil diff -b` | |
| 15 | + | |
| 16 | +This produces a graphical diff in HTML format and sends it to the | |
| 17 | +user’s default web browser for viewing. | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | +<a id="ui"></a> | |
| 22 | +## `fossil diff -tk` | |
| 23 | + | |
| 24 | +You may be surprised to learn that the prior feature doesn’t use any of | |
| 25 | +the skinning or chr-irome from Fossil UI. This is because it is meant as a | |
| 26 | +functional replacement for an older method of getting colorized diffs, | |
| 27 | +“`fossil diff -tk fossil set --global diff-command 'git diff --no-index' | |
| 28 | + | |
| 29 | +The flag permits it to diff files that aren’t inside a Git repository. | |
| 30 | + | |
| 31 | + | |
| 32 | +<a id="diffutils"></a> | |
| 33 | +## GNU Diffutils | |
| 34 | + | |
| 35 | +If your system is from 2016 or er, it may include [GNU Diffutils][gd] | |
| 36 | +3.4 or newer, which lets you say: | |
| 37 | + | |
| 38 | + fossil set --global diff-command 'diff -dwu --color=always' | |
| 39 | + | |
| 40 | +You might think you could give `--color=auto`, but that fails with | |
| 41 | +commands like “`fossil diff | less`” since the pipe turns the ouperspective of the underlying |
| --- a/www/colordiff.md | |
| +++ b/www/colordiff.md | |
| @@ -0,0 +1,41 @@ | |
| --- a/www/colordiff.md | |
| +++ b/www/colordiff.md | |
| @@ -0,0 +1,41 @@ | |
| 1 | # Colorized Diffs |
| 2 | |
| 3 | The oldest and most widely compatible method to get colorized diffs in |
| 4 | Fossil is to use its web UI: |
| 5 | |
| 6 | fossil ui --page '/vdiff?from=2024-04-01&to=trunk' |
| 7 | |
| 8 | That syntax is admittedly awkward, and it doesn’t work where “from” is |
| 9 | the current checkout. Fortunately, there are many other methods to get |
| 10 | colorized `diff` output from Fossil. |
| 11 | |
| 12 | |
| 13 | <a id="ui"></a> |
| 14 | ## `fossil diff -b` |
| 15 | |
| 16 | This produces a graphical diff in HTML format and sends it to the |
| 17 | user’s default web browser for viewing. |
| 18 | |
| 19 | |
| 20 | |
| 21 | <a id="ui"></a> |
| 22 | ## `fossil diff -tk` |
| 23 | |
| 24 | You may be surprised to learn that the prior feature doesn’t use any of |
| 25 | the skinning or chr-irome from Fossil UI. This is because it is meant as a |
| 26 | functional replacement for an older method of getting colorized diffs, |
| 27 | “`fossil diff -tk fossil set --global diff-command 'git diff --no-index' |
| 28 | |
| 29 | The flag permits it to diff files that aren’t inside a Git repository. |
| 30 | |
| 31 | |
| 32 | <a id="diffutils"></a> |
| 33 | ## GNU Diffutils |
| 34 | |
| 35 | If your system is from 2016 or er, it may include [GNU Diffutils][gd] |
| 36 | 3.4 or newer, which lets you say: |
| 37 | |
| 38 | fossil set --global diff-command 'diff -dwu --color=always' |
| 39 | |
| 40 | You might think you could give `--color=auto`, but that fails with |
| 41 | commands like “`fossil diff | less`” since the pipe turns the ouperspective of the underlying |
+6
-37
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -850,48 +850,19 @@ | ||
| 850 | 850 | We [covered this and the workaround for its lack](#comsplit) above. |
| 851 | 851 | |
| 852 | 852 | [3]: ./rebaseharm.md |
| 853 | 853 | |
| 854 | 854 | |
| 855 | -## <a id="cdiff"></a> Colorized Diffs | |
| 855 | +<a id="cdiff"></a> | |
| 856 | +## Colorized Diffs | |
| 856 | 857 | |
| 857 | 858 | When you run `git diff` on an ANSI X3.64 capable terminal, it uses color |
| 858 | 859 | to distinguish insertions, deletions, and replacements, but as of this |
| 859 | 860 | writing, `fossil diff` produces traditional uncolored [unified diff |
| 860 | 861 | format][udiff] output, suitable for producing a [patch file][pfile]. |
| 861 | 862 | |
| 862 | -Nevertheless, there are multiple ways to get colorized diff output from | |
| 863 | -Fossil: | |
| 864 | - | |
| 865 | -* The most direct method is to delegate diff behavior back to Git: | |
| 866 | - | |
| 867 | - fossil set --global diff-command 'git diff --no-index' | |
| 868 | - | |
| 869 | - The flag permits it to diff files that aren’t inside a Git repository. | |
| 870 | - | |
| 871 | -* Another method is to install [`colordiff`][cdiff] — included in | |
| 872 | - [many package systems][cdpkg] — then say: | |
| 873 | - | |
| 874 | - fossil set --global diff-command 'colordiff -wu' | |
| 875 | - | |
| 876 | - Because this is unconditional, unlike `git diff --color=auto`, you | |
| 877 | - will then have to remember to add the `-i` option to `fossil diff` | |
| 878 | - commands when you want color disabled, such as when producing | |
| 879 | - `patch(1)` files or piping diff output to another command that | |
| 880 | - doesn’t understand ANSI escape sequences. There’s an example of this | |
| 881 | - [below](#dstat). | |
| 882 | - | |
| 883 | -* Use the Fossil web UI to diff existing commits. | |
| 884 | - | |
| 885 | -* To diff the current working directory contents against some parent | |
| 886 | - instead, Fossil’s diff command can produce | |
| 887 | - colorized HTML output and open it in the OS’s default web browser. | |
| 888 | - For example, `fossil diff -by` will show side-by-side diffs. | |
| 889 | - | |
| 890 | -* Use the older `fossil diff --tk` option to do much the same using | |
| 891 | - Tcl/Tk instead of a browser. | |
| 892 | - | |
| 863 | +There are [many methods](./colordiff.md) for solving this. | |
| 893 | 864 | Viewed this way, Fossil doesn’t lack colorized diffs, it simply has |
| 894 | 865 | *one* method where they *aren’t* colorized. |
| 895 | 866 | |
| 896 | 867 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 897 | 868 | [pfile]: https://en.wikipedia.org/wiki/Patch_(Unix) |
| @@ -964,19 +935,17 @@ | ||
| 964 | 935 | a histogram in its default output mode rather than bare integers: |
| 965 | 936 | |
| 966 | 937 | fossil diff -i -v --from 2020-04-01 | diffstat |
| 967 | 938 | |
| 968 | 939 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 969 | -diff implementation, bypassing [your local `diff-command` setting][dcset]. | |
| 970 | -The `--numstat` option has no effect when you have an external diff | |
| 971 | -command set, and some diff command alternatives like | |
| 972 | -[`colordiff`][cdiff] (covered [above](#cdiff)) produce output that confuses `diffstat`. | |
| 940 | +diff implementation, bypassing [your local `diff-command` setting][dcset] | |
| 941 | +since the `--numstat` option has no effect when you have an external diff | |
| 942 | +command set. | |
| 973 | 943 | |
| 974 | 944 | If you leave off the `-v` flag in the second example, the `diffstat` |
| 975 | 945 | output won’t include info about any newly-added files. |
| 976 | 946 | |
| 977 | -[cdiff]: https://www.colordiff.org/ | |
| 978 | 947 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 979 | 948 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 980 | 949 | |
| 981 | 950 | |
| 982 | 951 | <a id="btnames"></a> |
| 983 | 952 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -850,48 +850,19 @@ | |
| 850 | We [covered this and the workaround for its lack](#comsplit) above. |
| 851 | |
| 852 | [3]: ./rebaseharm.md |
| 853 | |
| 854 | |
| 855 | ## <a id="cdiff"></a> Colorized Diffs |
| 856 | |
| 857 | When you run `git diff` on an ANSI X3.64 capable terminal, it uses color |
| 858 | to distinguish insertions, deletions, and replacements, but as of this |
| 859 | writing, `fossil diff` produces traditional uncolored [unified diff |
| 860 | format][udiff] output, suitable for producing a [patch file][pfile]. |
| 861 | |
| 862 | Nevertheless, there are multiple ways to get colorized diff output from |
| 863 | Fossil: |
| 864 | |
| 865 | * The most direct method is to delegate diff behavior back to Git: |
| 866 | |
| 867 | fossil set --global diff-command 'git diff --no-index' |
| 868 | |
| 869 | The flag permits it to diff files that aren’t inside a Git repository. |
| 870 | |
| 871 | * Another method is to install [`colordiff`][cdiff] — included in |
| 872 | [many package systems][cdpkg] — then say: |
| 873 | |
| 874 | fossil set --global diff-command 'colordiff -wu' |
| 875 | |
| 876 | Because this is unconditional, unlike `git diff --color=auto`, you |
| 877 | will then have to remember to add the `-i` option to `fossil diff` |
| 878 | commands when you want color disabled, such as when producing |
| 879 | `patch(1)` files or piping diff output to another command that |
| 880 | doesn’t understand ANSI escape sequences. There’s an example of this |
| 881 | [below](#dstat). |
| 882 | |
| 883 | * Use the Fossil web UI to diff existing commits. |
| 884 | |
| 885 | * To diff the current working directory contents against some parent |
| 886 | instead, Fossil’s diff command can produce |
| 887 | colorized HTML output and open it in the OS’s default web browser. |
| 888 | For example, `fossil diff -by` will show side-by-side diffs. |
| 889 | |
| 890 | * Use the older `fossil diff --tk` option to do much the same using |
| 891 | Tcl/Tk instead of a browser. |
| 892 | |
| 893 | Viewed this way, Fossil doesn’t lack colorized diffs, it simply has |
| 894 | *one* method where they *aren’t* colorized. |
| 895 | |
| 896 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 897 | [pfile]: https://en.wikipedia.org/wiki/Patch_(Unix) |
| @@ -964,19 +935,17 @@ | |
| 964 | a histogram in its default output mode rather than bare integers: |
| 965 | |
| 966 | fossil diff -i -v --from 2020-04-01 | diffstat |
| 967 | |
| 968 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 969 | diff implementation, bypassing [your local `diff-command` setting][dcset]. |
| 970 | The `--numstat` option has no effect when you have an external diff |
| 971 | command set, and some diff command alternatives like |
| 972 | [`colordiff`][cdiff] (covered [above](#cdiff)) produce output that confuses `diffstat`. |
| 973 | |
| 974 | If you leave off the `-v` flag in the second example, the `diffstat` |
| 975 | output won’t include info about any newly-added files. |
| 976 | |
| 977 | [cdiff]: https://www.colordiff.org/ |
| 978 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 979 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 980 | |
| 981 | |
| 982 | <a id="btnames"></a> |
| 983 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -850,48 +850,19 @@ | |
| 850 | We [covered this and the workaround for its lack](#comsplit) above. |
| 851 | |
| 852 | [3]: ./rebaseharm.md |
| 853 | |
| 854 | |
| 855 | <a id="cdiff"></a> |
| 856 | ## Colorized Diffs |
| 857 | |
| 858 | When you run `git diff` on an ANSI X3.64 capable terminal, it uses color |
| 859 | to distinguish insertions, deletions, and replacements, but as of this |
| 860 | writing, `fossil diff` produces traditional uncolored [unified diff |
| 861 | format][udiff] output, suitable for producing a [patch file][pfile]. |
| 862 | |
| 863 | There are [many methods](./colordiff.md) for solving this. |
| 864 | Viewed this way, Fossil doesn’t lack colorized diffs, it simply has |
| 865 | *one* method where they *aren’t* colorized. |
| 866 | |
| 867 | [cdpkg]: https://repology.org/project/colordiff/versions |
| 868 | [pfile]: https://en.wikipedia.org/wiki/Patch_(Unix) |
| @@ -964,19 +935,17 @@ | |
| 935 | a histogram in its default output mode rather than bare integers: |
| 936 | |
| 937 | fossil diff -i -v --from 2020-04-01 | diffstat |
| 938 | |
| 939 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 940 | diff implementation, bypassing [your local `diff-command` setting][dcset] |
| 941 | since the `--numstat` option has no effect when you have an external diff |
| 942 | command set. |
| 943 | |
| 944 | If you leave off the `-v` flag in the second example, the `diffstat` |
| 945 | output won’t include info about any newly-added files. |
| 946 | |
| 947 | [dcset]: https://fossil-scm.org/home/help?cmd=diff-command |
| 948 | [dst]: https://invisible-island.net/diffstat/diffstat.html |
| 949 | |
| 950 | |
| 951 | <a id="btnames"></a> |
| 952 |
+1
| --- www/mkindex.tcl | ||
| +++ www/mkindex.tcl | ||
| @@ -35,10 +35,11 @@ | ||
| 35 | 35 | checkin.wiki {Check-in Checklist} |
| 36 | 36 | childprojects.wiki {Child Projects} |
| 37 | 37 | chroot.md {Server Chroot Jail} |
| 38 | 38 | ckout-workflows.md {Check-Out Workflows} |
| 39 | 39 | co-vs-up.md {Checkout vs Update} |
| 40 | + colordiff.md {Colorized Diffs} | |
| 40 | 41 | copyright-release.html {Contributor License Agreement} |
| 41 | 42 | concepts.wiki {Fossil Core Concepts} |
| 42 | 43 | contact.md {Developer Contact Information} |
| 43 | 44 | containers.md {OCI Containers} |
| 44 | 45 | contribute.wiki {Contributing Code or Documentation To The Fossil Project} |
| 45 | 46 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -35,10 +35,11 @@ | |
| 35 | checkin.wiki {Check-in Checklist} |
| 36 | childprojects.wiki {Child Projects} |
| 37 | chroot.md {Server Chroot Jail} |
| 38 | ckout-workflows.md {Check-Out Workflows} |
| 39 | co-vs-up.md {Checkout vs Update} |
| 40 | copyright-release.html {Contributor License Agreement} |
| 41 | concepts.wiki {Fossil Core Concepts} |
| 42 | contact.md {Developer Contact Information} |
| 43 | containers.md {OCI Containers} |
| 44 | contribute.wiki {Contributing Code or Documentation To The Fossil Project} |
| 45 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -35,10 +35,11 @@ | |
| 35 | checkin.wiki {Check-in Checklist} |
| 36 | childprojects.wiki {Child Projects} |
| 37 | chroot.md {Server Chroot Jail} |
| 38 | ckout-workflows.md {Check-Out Workflows} |
| 39 | co-vs-up.md {Checkout vs Update} |
| 40 | colordiff.md {Colorized Diffs} |
| 41 | copyright-release.html {Contributor License Agreement} |
| 42 | concepts.wiki {Fossil Core Concepts} |
| 43 | contact.md {Developer Contact Information} |
| 44 | containers.md {OCI Containers} |
| 45 | contribute.wiki {Contributing Code or Documentation To The Fossil Project} |
| 46 |
| --- www/permutedindex.html | ||
| +++ www/permutedindex.html | ||
| @@ -35,10 +35,11 @@ | ||
| 35 | 35 | <li><a href="checkin.wiki">Check-in Checklist</a></li> |
| 36 | 36 | <li><a href="ckout-workflows.md">Check-Out Workflows</a></li> |
| 37 | 37 | <li><a href="foss-cklist.wiki">Checklist For Successful Open-Source Projects</a></li> |
| 38 | 38 | <li><a href="co-vs-up.md">Checkout vs Update</a></li> |
| 39 | 39 | <li><a href="childprojects.wiki">Child Projects</a></li> |
| 40 | +<li><a href="colordiff.md">Colorized Diffs</a></li> | |
| 40 | 41 | <li><a href="build.wiki">Compiling and Installing Fossil</a></li> |
| 41 | 42 | <li><a href="contribute.wiki">Contributing Code or Documentation To The Fossil Project</a></li> |
| 42 | 43 | <li><a href="copyright-release.html">Contributor License Agreement</a></li> |
| 43 | 44 | <li><a href="private.wiki">Creating, Syncing, and Deleting Private Branches</a></li> |
| 44 | 45 | <li><a href="customskin.md">Custom Skins</a></li> |
| 45 | 46 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -35,10 +35,11 @@ | |
| 35 | <li><a href="checkin.wiki">Check-in Checklist</a></li> |
| 36 | <li><a href="ckout-workflows.md">Check-Out Workflows</a></li> |
| 37 | <li><a href="foss-cklist.wiki">Checklist For Successful Open-Source Projects</a></li> |
| 38 | <li><a href="co-vs-up.md">Checkout vs Update</a></li> |
| 39 | <li><a href="childprojects.wiki">Child Projects</a></li> |
| 40 | <li><a href="build.wiki">Compiling and Installing Fossil</a></li> |
| 41 | <li><a href="contribute.wiki">Contributing Code or Documentation To The Fossil Project</a></li> |
| 42 | <li><a href="copyright-release.html">Contributor License Agreement</a></li> |
| 43 | <li><a href="private.wiki">Creating, Syncing, and Deleting Private Branches</a></li> |
| 44 | <li><a href="customskin.md">Custom Skins</a></li> |
| 45 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -35,10 +35,11 @@ | |
| 35 | <li><a href="checkin.wiki">Check-in Checklist</a></li> |
| 36 | <li><a href="ckout-workflows.md">Check-Out Workflows</a></li> |
| 37 | <li><a href="foss-cklist.wiki">Checklist For Successful Open-Source Projects</a></li> |
| 38 | <li><a href="co-vs-up.md">Checkout vs Update</a></li> |
| 39 | <li><a href="childprojects.wiki">Child Projects</a></li> |
| 40 | <li><a href="colordiff.md">Colorized Diffs</a></li> |
| 41 | <li><a href="build.wiki">Compiling and Installing Fossil</a></li> |
| 42 | <li><a href="contribute.wiki">Contributing Code or Documentation To The Fossil Project</a></li> |
| 43 | <li><a href="copyright-release.html">Contributor License Agreement</a></li> |
| 44 | <li><a href="private.wiki">Creating, Syncing, and Deleting Private Branches</a></li> |
| 45 | <li><a href="customskin.md">Custom Skins</a></li> |
| 46 |