Document the meaning of colored version numbers in the manpage of opa…

…m show
ocaml · Jan 20, 2025 · be365d8 · be365d8
1 parent af72831
commit be365d8
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 1 deletion.
diff --git a/master_changes.md b/master_changes.md
@@ -190,6 +190,7 @@ users)
   * Manual: add information when flags (`avoid-version`, `deprecated`) were introduced [#6320 @hannesm]
   * Add winget command for installing opam [#6338 @tobil4sk]
   * Fix broken link to non-existing archlinux community repo [#6361 @juergenhoetzel]
+  * Document the meaning of colored version numbers in the manpage of `opam show` [#6358 @kit-ty-kate]
 
 ## Security fixes
 

diff --git a/src/client/opamCommands.ml b/src/client/opamCommands.ml
@@ -921,7 +921,17 @@ let show cli =
         available packages as well as a short description for each.";
     `P "Paths to package definition files or to directories containing package \
         definitions can also be specified, in which case the corresponding \
-        metadata will be shown."
+        metadata will be shown.";
+    `P "Note: on terminal supporting it, version numbers can be colored the \
+        following ways:";
+    `Noblank;
+    `I ("-", "Versions installed the current switch are displayed bold and magenta");
+    `Noblank;
+    `I ("-", "Versions installed in other switches are displayed bold");
+    `Noblank;
+    `I ("-", "Versions not available on the current platform are displayed crossed and red");
+    `Noblank;
+    `I ("-", "Versions tagged with the avoid-version or deprecated flag are displayed gray");
   ] in
   let fields =
     mk_opt ~cli cli_original ["f";"field"] "FIELDS"

diff --git a/src/client/opamListCommand.ml b/src/client/opamListCommand.ml
@@ -506,6 +506,7 @@ let field_of_string ~raw =
     | Some f -> Field f
     | None -> OpamConsole.error_and_exit `Bad_arguments "No printer for %S" s
 
+(* NOTE: upon changes, please update the man page section in opamCommands.ml *)
 let version_color st nv =
   let installed = (* (in any switch) *)
     OpamGlobalState.installed_versions st.switch_global nv.name