Add usage examples and command aliases (#14)

timebertt · May 22, 2024 · 8b03004 · 8b03004
1 parent 6617ae2
commit 8b03004
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,14 @@
 
 🚀 *Time-travel through your cluster* 🕰️
 
+## About
+
+`kubectl-history` is a [kubectl plugin](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) and can be invoked as `kubectl history`, or for short `k history`.
+
+The history plugin allows you to go back in time in the history of rollouts and answers common questions like "Why was my Deployment rolled?"
+
+It gives more output than `kubectl rollout history` and is easier to use than `kubectl get replicaset` or `kubectl get controllerrevision`.
+
 ## Installation
 
 ```bash
@@ -10,45 +18,69 @@ go install github.com/timebertt/kubectl-history@latest
 
 ## Usage
 
-`kubectl-history` is a [kubectl plugin](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) and can be invoked as `kubectl history`.
+### `k history get` / `k history list`
+
+Get the rollout history of a workload resource (`Deployment`, `StatefulSet`, or `DaemonSet`).
+
+The history is based on the `ReplicaSets`/`ControllerRevisions` still in the system. I.e., the history is limited by the
+configured `revisionHistoryLimit`.
 
-### `kubectl history get`
+By default, all revisions are printed as a list. If the `--revision` flag is given, the selected revision is printed
+instead.
 
 ```bash
-$ k history get deploy demo
-NAME              REVISION   AGE
-demo-75554748b7   1          2m
-demo-6b6f8d8b5f   2          43s
-demo-7d7cf9bc6    3          5s
+$ k history get deploy nginx -owide
+NAME               REVISION   AGE   CONTAINERS   IMAGES
+nginx-77b4fdf86c   1          22m   nginx        nginx
+nginx-7bf8c77b5b   2          21m   nginx        nginx:latest
+nginx-7bb88f5ff4   3          20m   nginx        nginx:1.24
+
+$ k history get deploy nginx -r -1 -oyaml
+apiVersion: apps/v1
+kind: ReplicaSet
+metadata:
+  name: nginx-7bb88f5ff4
+...
 ```
 
-### `kubectl history diff`
+This is similar to using `k get replicaset` or `k get controllerrevision`, but allows easy selection of the relevant objects and returns a sorted list.
+This is also similar to `k rollout history`, but doesn't only print revision numbers.
+
+### `k history diff` / `k history why`
+
+Compare multiple revisions of a workload resource (`Deployment`, `StatefulSet`, or `DaemonSet`).
+A.k.a., "Why was my Deployment rolled?"
+
+The history is based on the `ReplicaSets`/`ControllerRevisions` still in the system. I.e., the history is limited by the
+configured `revisionHistoryLimit`.
+
+By default, the latest two revisions are compared. The `--revision` flag allows selecting the revisions to compare.
 
 ```bash
-$ k history diff deploy demo
-comparing revisions 2 and 3 of deployment.apps/demo
---- /var/folders/d8/x7ty7dh12sg7vrq374x52pk80000gq/T/deployment.apps_demo-903550842/2-demo-6b6f8d8b5f.yaml	2023-08-09 08:33:47
-+++ /var/folders/d8/x7ty7dh12sg7vrq374x52pk80000gq/T/deployment.apps_demo-903550842/3-demo-7d7cf9bc6.yaml	2023-08-09 08:33:47
-@@ -4,7 +4,7 @@
-     app: demo
+$ k history diff deploy nginx
+comparing revisions 2 and 3 of deployment.apps/nginx
+--- /var/folders/d8/x7ty7dh12sg7vrq374x52pk80000gq/T/deployment.apps_nginx-2577026088/2-nginx-7bf8c77b5b.yaml	2024-05-22 23:16:51
++++ /var/folders/d8/x7ty7dh12sg7vrq374x52pk80000gq/T/deployment.apps_nginx-2577026088/3-nginx-7bb88f5ff4.yaml	2024-05-22 23:16:51
+@@ -7,7 +7,7 @@
+     app: nginx
  spec:
    containers:
--  - image: nginx:1.24
-+  - image: nginx:1.25-alpine
-     imagePullPolicy: IfNotPresent
+-  - image: nginx:latest
++  - image: nginx:1.24
+     imagePullPolicy: Always
      name: nginx
      resources: {}
 ```
 
-The `kubectl history diff` command uses `diff -u -N` to compare revisions by default.
+The `k history diff` command uses `diff -u -N` to compare revisions by default.
 It also respects the `KUBECTL_EXTERNAL_DIFF` environment variable like the `kubectl diff` command.
 To get a nicer diff view, you can use one of these:
 
 ```bash
-# add color to the diff output
-k history diff deploy demo | colordiff
-# specify an external diff programm
-KUBECTL_EXTERNAL_DIFF="colordiff -u" k history diff deploy demo
-# show diff in VS Code
-KUBECTL_EXTERNAL_DIFF="code --diff --wait" k history diff deploy demo
+# Add color to the diff output
+k history diff deploy nginx | colordiff
+# Specify an external diff programm
+KUBECTL_EXTERNAL_DIFF="colordiff -u" k history diff deploy nginx
+# Show diff in VS Code
+KUBECTL_EXTERNAL_DIFF="code --diff --wait" k history diff deploy nginx
 ```
diff --git a/pkg/cmd/diff/diff.go b/pkg/cmd/diff/diff.go
@@ -50,8 +50,42 @@ func NewCommand(f util.Factory, streams genericclioptions.IOStreams) *cobra.Comm
 	o := NewOptions(streams)
 
 	cmd := &cobra.Command{
-		Use:   "diff (TYPE[.VERSION][.GROUP] NAME | TYPE[.VERSION][.GROUP]/NAME)",
+		Use:     "diff (TYPE[.VERSION][.GROUP] NAME | TYPE[.VERSION][.GROUP]/NAME)",
+		Aliases: []string{"why"},
+
 		Short: "Compare multiple revisions of a workload resource",
+		Long: `Compare multiple revisions of a workload resource (Deployment, StatefulSet, or DaemonSet).
+  A.k.a., "Why was my Deployment rolled?"
+
+ The history is based on the ReplicaSets/ControllerRevisions still in the system. I.e., the history is limited by the
+configured revisionHistoryLimit.
+
+ By default, the latest two revisions are compared. The --revision flag allows selecting the revisions to compare.
+
+ KUBECTL_EXTERNAL_DIFF environment variable can be used to select your own diff command. Users can use external commands
+with params too, example: KUBECTL_EXTERNAL_DIFF="colordiff -N -u"
+
+ By default, the "diff" command available in your path will be run with the "-u" (unified diff) and "-N" (treat absent
+files as empty) options.`,
+		Example: `  # Find out why the nginx Deployment was rolled: compare the latest two revisions
+  kubectl history diff deploy nginx
+  
+  # Compare the first and third revision
+  kubectl history diff deploy nginx --revision=1,3
+  
+  # Compare the previous revision and the revision before that
+  kubectl history diff deploy nginx --revision=-2
+  
+  # Add color to the diff output
+  kubectl history diff deploy nginx | colordiff
+  
+  # Specify an external diff programm
+  KUBECTL_EXTERNAL_DIFF="colordiff -u" kubectl history diff deploy nginx
+  
+  # Show diff in VS Code
+  KUBECTL_EXTERNAL_DIFF="code --diff --wait" kubectl history diff deploy nginx
+`,
+
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 

diff --git a/pkg/cmd/get/get.go b/pkg/cmd/get/get.go
@@ -35,8 +35,27 @@ func NewCommand(f util.Factory, streams genericclioptions.IOStreams) *cobra.Comm
 	o := NewOptions(streams)
 
 	cmd := &cobra.Command{
-		Use:   "get (TYPE[.VERSION][.GROUP] NAME | TYPE[.VERSION][.GROUP]/NAME)",
-		Short: "Get the history of a workload resource",
+		Use:     "get (TYPE[.VERSION][.GROUP] NAME | TYPE[.VERSION][.GROUP]/NAME)",
+		Aliases: []string{"list", "ls"},
+
+		Short: "Get the rollout history of a workload resource",
+		Long: `Get the rollout history of a workload resource (Deployment, StatefulSet, or DaemonSet).
+
+ The history is based on the ReplicaSets/ControllerRevisions still in the system. I.e., the history is limited by the
+configured revisionHistoryLimit.
+
+ By default, all revisions are printed as a list. If the --revision flag is given, the selected revision is printed
+instead.
+`,
+		Example: `  # Get all revisions of the nginx Deployment
+  kubectl history get deploy nginx
+  
+  # Print additional columns like the revisions' images
+  kubectl history get deploy nginx -o wide
+  
+  # Get the latest revision in YAML
+  kubectl history get deploy nginx --revision=-1 -o yaml`,
+
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()