CLI stabilization effort

[tomberek]

This is a DRAFT
Tracking for the stabilizing effort:

Tasks

1. consider feature mappings with legacy CLI (not expected to be 1-1)
2. review correctness of command
3. do all --help options make sense
4. create any issues or PRs to resolve the above, we will link it here for tracking
5. verify "ready for stabilization"

The goal isn't to stabilize the whole CLI at once. A bunch of less-frequent commands can wait for a bit while we focus on the most important ones.

First batch of stabilization

• nix daemon
  • Port the flags of nix-daemon to nix daemon #8788
  • Test the nix daemon command #9647
• nix nar
  • Stabilise nix nar and subcommands #8875
  • request for contributions: make this usable as a general utility. eg: the unpack/extract
  • rename to pack/unpack
  • (non-blockers) refine other subcommands such as cat, ls, tar conversions
• nix hash
  • rename sub-commands: Stabilise nix hash and subcommands #8876
  • nix hash convert [--type sha256] --from (base16|...|sri) --to base64 strings...
    • Add nix hash convert #9452
  • nix hash path
    • nix hash path, text hashing for nix store add, and preparatory refactors #9815
• nix key
  • nix key: Add a newline to the output #8849
  • Stabilise nix key #8877
• new-command: nix config
  • Check
  • Show
• nix store
  • nix store gc nix store gc: Stabilize #7608
    • Make 'nix store gc' use the auto-GC policy  #7851 : honor min-free and max-free config options, and remove --max flag
      • note: --max is closer to the understanding of --min and can/should also be idempotent relative to disk space?
  • nix store ping Stabilise nix store ping #8914
    • trusted returned as integer is awkward, should be a boolean
    • rename to nix store info
  • nix store add-file,nix store add-path Stabilise nix store add #8915
    • --recursive should be the default due to history and to match string-interpolation behavior
    • need clarification of how to specify outputHashMode, outputHashAlgo, etc.
    • expose as --key value or --value1|--value2 create PR to CLI guidelines
  • nix store import, nix store export Not a blocker for stabilisation
  • nix store delete
    • provide better information about why something was not deleted Not required for stabilisation
      • example: Cannot delete store path with no roots #6141
    • Make nix store delete ./result work #9475 Not required for stabilisation
  • nix store optimise
    • stabilise as is!

To be discussed

Stuff that hasn't been processed yet

• nix copy

  • Stabilize nix copy #8011

• nix describe-stores nix help-stores

  • nix describe-stores --json format is not extensible #7824
  • Move nix {show-config,doctor} under subcommands #7672

• nix path-info

  • Categorize path-info and C++ path info fields #10498
  • Rework the store-side interfaceo

• nix build

  • https://discourse.nixos.org/t/2024-02-26-nix-team-meeting-minutes-128/40496#nix-build-7

• nix develop

• nix print-dev-env

• nix shell

• nix run

• nix search

• nix repl

  • Technically already stable

• nix eval

• nix bundle

• nix edit

• nix fmt

• nix log

• nix registry

• nix why-depends

• nix derivation

  • maybe Derivation JSON env does not adhere to the JSON guidelines #9866

• nix profile: nix profile has bad UX #7966

• nix realisation

• nix upgrade-nix

• nix flake

Global concerns

• settings
  • Triage and break up the global settings #5638
  • Move settings from Settings to LocalStoreConfig #7740
  • Hide experimental settings #7609
• config
• flags
  • Remove --print-build-logs from various commands #7820
  • Stuctured command stability #7611
• layering, see: [RFC 0136] A plan to stabilize the new CLI and Flakes incrementally rfcs#136
• (non-blocking) Can't add a file from stdin #7773

Blocked on installables

• nix shell
  • Rename 'nix shell' #4715
  • nix shell does not insert PATH items in command line order #7905
  • ...
• ...

To stabilise in a later batch

These are low priority and have more involved background issues we have to clarify first

• nix store cat
• nix store ls
• nix store copy-log
• nix store copy-sigs
• nix store diff-closures
• nix store make-content-addressed
• nix store path-from-hash-part
• nix store prefetch-file
• nix store repair
• nix store verify
  • document the defaults for the options
  • ensure that sigs-needed only takes into account the cryptographic portion of the key, not the name
• nix store sign
  • see previous: Unsigned derivations uploaded to S3 #6960 (comment)
  • QUESTION: sign only until other signatures encountered (limited -r)
  • --key-file - to read key from stdin, exclusive with --stdin, but then how to pass both via pipe?
  • QUESTION: add a --pipe FD for which --stdin is alias for --pipe /dev/fd/0?

References

CLI Guidelines
legacy CLI mapping

[Ericson2314]

#7740 / #5638 being hard I think it something to think about prior to command stabilization.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-01-27-nix-team-meeting-minutes-27/25434/1

[fricklerhandwerk]

Discussed in the Nix team meeting 2023-02-10:

Decision: work through one complete command at a time and write down the process. once finished and everyone is confident to reproduce that process on one's own, do the rest of the work in parallel.

Complete discussion

• @tomberek will clarify the exact things to do
  • @Ericson2314: the idea was to take one command at a time to figure out these things to begin with
  • @fricklerhandwerk: why don't we do it together for one command?
  • @Ericson2314: we already started with nix store gc
  • @fricklerhandwerk: let's take one hour together in the work meetings to attack this and write down what we do. when one command is finished (it is likely to take months at that pace), and everyone is confident to reproduce the process on one's own given the documentation we write, we can parallelise it for all the other commands
    • agreement
    • @roberth: several months are a blip in relation to how long it took to develop the new CLI anyway
  • @thufschmitt: will make a PR to put on the agenda for next time
    • won't be there myself though

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-02-10-nix-team-meeting-minutes-31/25438/1

[Ericson2314]

Two topics (with my PR fixes, if we like my solution) that I think would be good to track:

• Gating experimental settings on experimental features --- Hide experimental settings #7609
• Hiding freeform prose on experimental topics in --help --- Stuctured command stability #7611

(My middle PR, #7610, corresponds to #7820 already listed here, so there is no need to link the issue directly.)

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-02-10-nix-team-meeting-minutes-32/25442/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-44/25546/1