Skip to content

Commit 8a156e4

Browse files
HeavyWombatHeavyWombat
committed
Tweak README file
Add section with command-line tool command documentation. Add tool to generate command-line tool command documentation. Remove the `snap` section, since this is no longer maintained.
1 parent 28237d1 commit 8a156e4

File tree

11 files changed

+313
-11
lines changed

11 files changed

+313
-11
lines changed

‎.docs/commands/dyff.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## dyff
2+
3+
dyff
4+
5+
### Synopsis
6+
7+
8+
δyƒƒ /ˈdʏf/ - a diff tool for YAML files, and sometimes JSON. Also, It
9+
can transform YAML to JSON, and vice versa. The order of keys in hashes
10+
is preserved during the conversion.
11+
12+
13+
### Options
14+
15+
```
16+
-c, --color specify color usage: on, off, or auto (default auto)
17+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
18+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
19+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
20+
-h, --help help for dyff
21+
```
22+
23+
### SEE ALSO
24+
25+
* [dyff between](dyff_between.md) - Compare differences between input files from and to
26+
* [dyff json](dyff_json.md) - Converts input documents into JSON format
27+
* [dyff last-applied](dyff_last-applied.md) - Compare differences between the current state and the one stored in Kubernetes last-applied configuration
28+
* [dyff version](dyff_version.md) - Shows the version of this tool
29+
* [dyff yaml](dyff_yaml.md) - Converts input documents into YAML format
30+

‎.docs/commands/dyff_between.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
## dyff between
2+
3+
Compare differences between input files from and to
4+
5+
### Synopsis
6+
7+
8+
Compares differences between files and displays the delta. Supported input file
9+
types are: YAML (http://yaml.org/) and JSON (http://json.org/).
10+
11+
12+
```
13+
dyff between [flags] <from> <to>
14+
```
15+
16+
### Options
17+
18+
```
19+
-i, --ignore-order-changes ignore order changes in lists
20+
--ignore-whitespace-changes ignore leading or trailing whitespace changes
21+
--detect-kubernetes detect kubernetes entities (default true)
22+
--additional-identifier stringArray use additional identifier candidates in named entry lists
23+
--filter strings filter reports to a subset of differences based on supplied arguments
24+
--exclude strings exclude reports from a set of differences based on supplied arguments
25+
--filter-regexp strings filter reports to a subset of differences based on supplied regular expressions
26+
--exclude-regexp strings exclude reports from a set of differences based on supplied regular expressions
27+
-v, --ignore-value-changes exclude changes in values
28+
--detect-renames enable detection for renames (document level for Kubernetes resources) (default true)
29+
-o, --output string specify the output style, supported styles: human, brief, github, gitlab, gitea (default "human")
30+
-b, --omit-header omit the dyff summary header
31+
-s, --set-exit-code set program exit code, with 0 meaning no difference, 1 for differences detected, and 255 for program error
32+
-l, --no-table-style do not place blocks next to each other, always use one row per text block
33+
-x, --no-cert-inspection disable x509 certificate inspection, compare as raw text
34+
-g, --use-go-patch-style use Go-Patch style paths in outputs
35+
--minor-change-threshold float minor change threshold (default 0.1)
36+
--multi-line-context-lines int multi-line context lines (default 4)
37+
--swap Swap 'from' and 'to' for comparison
38+
--chroot string change the root level of the input file to another point in the document
39+
--chroot-of-from string only change the root level of the from input file
40+
--chroot-of-to string only change the root level of the to input file
41+
--chroot-list-to-documents in case the change root points to a list, treat this list as a set of documents and not as the list itself
42+
-h, --help help for between
43+
```
44+
45+
### Options inherited from parent commands
46+
47+
```
48+
-c, --color specify color usage: on, off, or auto (default auto)
49+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
50+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
51+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
52+
```
53+
54+
### SEE ALSO
55+
56+
* [dyff](dyff.md) - dyff
57+

‎.docs/commands/dyff_json.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## dyff json
2+
3+
Converts input documents into JSON format
4+
5+
### Synopsis
6+
7+
8+
Converts input document into JSON format while preserving the order of all keys.
9+
10+
11+
```
12+
dyff json [flags] <file-location> ...
13+
```
14+
15+
### Options
16+
17+
```
18+
-p, --plain output in plain style without any highlighting
19+
-r, --restructure restructure map keys in reasonable order
20+
-O, --omit-indent-helper omit indent helper lines in highlighted output
21+
-i, --in-place overwrite input file with output of this command
22+
-h, --help help for json
23+
```
24+
25+
### Options inherited from parent commands
26+
27+
```
28+
-c, --color specify color usage: on, off, or auto (default auto)
29+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
30+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
31+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
32+
```
33+
34+
### SEE ALSO
35+
36+
* [dyff](dyff.md) - dyff
37+

‎.docs/commands/dyff_last-applied.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## dyff last-applied
2+
3+
Compare differences between the current state and the one stored in Kubernetes last-applied configuration
4+
5+
### Synopsis
6+
7+
8+
Kubernetes resource YAML (or JSON) contain the previously used configuration of
9+
that resource in the metadata. For convenience, the respective metadata is used
10+
to compare it against the current configuration.
11+
12+
13+
```
14+
dyff last-applied [flags]
15+
```
16+
17+
### Options
18+
19+
```
20+
-i, --ignore-order-changes ignore order changes in lists
21+
--ignore-whitespace-changes ignore leading or trailing whitespace changes
22+
--detect-kubernetes detect kubernetes entities (default true)
23+
--additional-identifier stringArray use additional identifier candidates in named entry lists
24+
--filter strings filter reports to a subset of differences based on supplied arguments
25+
--exclude strings exclude reports from a set of differences based on supplied arguments
26+
--filter-regexp strings filter reports to a subset of differences based on supplied regular expressions
27+
--exclude-regexp strings exclude reports from a set of differences based on supplied regular expressions
28+
-v, --ignore-value-changes exclude changes in values
29+
--detect-renames enable detection for renames (document level for Kubernetes resources) (default true)
30+
-o, --output string specify the output style, supported styles: human, brief, github, gitlab, gitea (default "human")
31+
-b, --omit-header omit the dyff summary header
32+
-s, --set-exit-code set program exit code, with 0 meaning no difference, 1 for differences detected, and 255 for program error
33+
-l, --no-table-style do not place blocks next to each other, always use one row per text block
34+
-x, --no-cert-inspection disable x509 certificate inspection, compare as raw text
35+
-g, --use-go-patch-style use Go-Patch style paths in outputs
36+
--minor-change-threshold float minor change threshold (default 0.1)
37+
--multi-line-context-lines int multi-line context lines (default 4)
38+
-h, --help help for last-applied
39+
```
40+
41+
### Options inherited from parent commands
42+
43+
```
44+
-c, --color specify color usage: on, off, or auto (default auto)
45+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
46+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
47+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
48+
```
49+
50+
### SEE ALSO
51+
52+
* [dyff](dyff.md) - dyff
53+

‎.docs/commands/dyff_version.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
## dyff version
2+
3+
Shows the version of this tool
4+
5+
### Synopsis
6+
7+
Shows the version of this tool
8+
9+
```
10+
dyff version [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
-h, --help help for version
17+
```
18+
19+
### Options inherited from parent commands
20+
21+
```
22+
-c, --color specify color usage: on, off, or auto (default auto)
23+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
24+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
25+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
26+
```
27+
28+
### SEE ALSO
29+
30+
* [dyff](dyff.md) - dyff
31+

‎.docs/commands/dyff_yaml.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## dyff yaml
2+
3+
Converts input documents into YAML format
4+
5+
### Synopsis
6+
7+
8+
Converts input document into YAML format while preserving the order of all keys.
9+
10+
11+
```
12+
dyff yaml [flags] <file-location> ...
13+
```
14+
15+
### Options
16+
17+
```
18+
-p, --plain output in plain style without any highlighting
19+
-r, --restructure restructure map keys in reasonable order
20+
-O, --omit-indent-helper omit indent helper lines in highlighted output
21+
-i, --in-place overwrite input file with output of this command
22+
-h, --help help for yaml
23+
```
24+
25+
### Options inherited from parent commands
26+
27+
```
28+
-c, --color specify color usage: on, off, or auto (default auto)
29+
-w, --fixed-width int disable terminal width detection and use provided fixed value (default -1)
30+
-k, --preserve-key-order-in-json use ordered keys during JSON decoding (non standard behavior)
31+
-t, --truecolor specify true color usage: on, off, or auto (default auto)
32+
```
33+
34+
### SEE ALSO
35+
36+
* [dyff](dyff.md) - dyff
37+

‎README.md

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ Input files can be local files (filesystem path), remote files (URI), or the sta
2323

2424
All orders of keys in hashes are preserved during processing and output to the terminal, most notably in the sub-commands to convert YAML to JSON and vice versa.
2525

26+
## Command documentation
27+
28+
See [command documentation](.docs/commands/dyff.md) for details about each command and its flags.
29+
2630
## Use cases and examples
2731

2832
- Show differences between the live configuration of Kubernetes resources and what would be applied (`kubectl` version >= `v1.20.0`):
@@ -38,7 +42,7 @@ All orders of keys in hashes are preserved during processing and output to the t
3842
![dyff between example with kubectl diff](.docs/dyff-between-kubectl-diff.png?raw=true "dyff in kubectl diff example")
3943

4044
The `--set-exit-code` flag is required so that the `dyff` exit code matches `kubectl` expectations. An exit code `0` refers to no differences, `1` in case differences are detected. Other exit codes are treated as program issues.
41-
45+
4246
_Note:_ Versions of `kubectl` older than `v1.20.0` did not split the environment variable into field, therefore you cannot use command arguments. In this case, you need to wrap the `dyff` command with its argument into a helper shell script and use this instead.
4347

4448
- Show the differences between two versions of [`cf-deployment`](https://github.com/cloudfoundry/cf-deployment/) YAMLs:
@@ -119,16 +123,6 @@ On macOS, `dyff` is also [available via MacPorts](https://ports.macports.org/por
119123
sudo port install dyff
120124
```
121125

122-
### Snap
123-
124-
It is [available in the `snapcraft` store](https://snapcraft.io/dyff) in the Productivity section.
125-
126-
```bash
127-
snap install dyff
128-
```
129-
130-
_Please note:_ Since `dyff` needs to use `strict` confinement due to otherwise manual clearance requirements, there are some limits to its usage. Most notably, users reported that in `strict` confinement reading files from the temporary directory does not work. This makes it impossible to use it in the `kubectl diff` use case. Consider using `brew`, or pre-built binaries instead.
131-
132126
### Pre-built binaries in GitHub
133127

134128
Prebuilt binaries can be [downloaded from the GitHub Releases section](https://github.com/homeport/dyff/releases/latest).

‎cmd/gendoc/main.go

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Copyright © 2025 The Homeport Team
2+
//
3+
// Permission is hereby granted, free of charge, to any person obtaining a copy
4+
// of this software and associated documentation files (the "Software"), to deal
5+
// in the Software without restriction, including without limitation the rights
6+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
// copies of the Software, and to permit persons to whom the Software is
8+
// furnished to do so, subject to the following conditions:
9+
//
10+
// The above copyright notice and this permission notice shall be included in
11+
// all copies or substantial portions of the Software.
12+
//
13+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19+
// THE SOFTWARE.
20+
21+
package main
22+
23+
import (
24+
"log"
25+
"os"
26+
27+
"github.com/homeport/dyff/internal/cmd"
28+
"github.com/spf13/cobra/doc"
29+
)
30+
31+
const targetDir = ".docs/commands"
32+
33+
func main() {
34+
if err := mainE(); err != nil {
35+
log.Fatal(err)
36+
}
37+
}
38+
39+
func mainE() error {
40+
rcmd := cmd.NewRootCmd()
41+
rcmd.Use = "dyff"
42+
rcmd.Short = "dyff"
43+
rcmd.DisableAutoGenTag = true
44+
45+
if err := os.RemoveAll(targetDir); err != nil {
46+
return err
47+
}
48+
49+
if err := os.MkdirAll(targetDir, os.FileMode(0755)); err != nil {
50+
return err
51+
}
52+
53+
return doc.GenMarkdownTree(rcmd, targetDir)
54+
}

‎go.mod

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ require github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3
2626

2727
require (
2828
github.com/BurntSushi/toml v1.4.0 // indirect
29+
github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
2930
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
3031
github.com/go-logr/logr v1.4.2 // indirect
3132
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
@@ -37,6 +38,7 @@ require (
3738
github.com/mattn/go-isatty v0.0.20 // indirect
3839
github.com/mitchellh/go-ps v1.0.0 // indirect
3940
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
41+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
4042
github.com/spf13/pflag v1.0.6 // indirect
4143
github.com/stretchr/testify v1.10.0 // indirect
4244
github.com/virtuald/go-ordered-json v0.0.0-20170621173500-b18e6e673d74 // indirect

‎go.sum

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
github.com/BurntSushi/toml v1.4.0 h1:kuoIxZQy2WRRk1pttg9asf+WVv6tWQuBNVmK8+nqPr0=
22
github.com/BurntSushi/toml v1.4.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
3+
github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0=
34
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
45
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
56
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -59,6 +60,7 @@ github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRI
5960
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
6061
github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
6162
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
63+
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
6264
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
6365
github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 h1:n661drycOFuPLCN3Uc8sB6B/s6Z4t2xvBgU1htSHuq8=
6466
github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=

0 commit comments

Comments
 (0)