feat(cli): add --human and --sort-size to ipfs ls - #11408
Conversation
capricornusx
commented
Jul 25, 2026
capricornusx
commented
- --human (-H): SI human-readable sizes in text output (humanize.Bytes)
- --sort-size (-S): sort directory entries by size, largest first
- Validation: --sort-size + --stream and --sort-size + --size=false errors
- Unit tests for formatSize and sort helpers
- CLI integration tests for both flags
- Changelog highlight in v0.44
- --human (-H): SI human-readable sizes in text output (humanize.Bytes) - --sort-size (-S): sort directory entries by size, largest first - Validation: --sort-size + --stream and --sort-size + --size=false errors - Unit tests for formatSize and sort helpers - CLI integration tests for both flags - Changelog highlight in v0.44
The tests covering --sort-size could not detect a broken feature. The unit tests copied the comparator into the test body and sorted with their own copy, so they passed regardless of what ls.go did. The CLI tests named each fixture after its size, which left alphabetical order and size order in agreement, so every ordering subtest passed even with --sort-size disabled outright. - extract lsLinkByName and lsLinkBySize so the tests exercise shipped code - point the unit tests at those two functions - name fixtures so their alphabetical order disagrees with their sizes - pin the real directory behaviour: UnixFS directories carry no Filesize, so they sort as 0, tie with empty files and break by name rather than landing strictly last
Passing --sort-size together with --stream or --size=false made /api/v0/ls answer 500 Internal Server Error, telling API clients the server had broken when the caller had simply combined flags that cannot work together. Clients that retry on 5xx would retry a request that can never succeed. cmds.ErrClient maps to 400, matching how the rest of core/commands reports caller mistakes. CLI output is unchanged.
The help for --human advertised "1K 234M 2G", which no kubo command has
ever printed. All three use humanize.Bytes, so the real output is SI with
a space: 1.2 kB, 234 MB, 2.0 GB. The stale example was copied into
'ipfs ls' from the two commands that already carried it, so correct all
three together.
- ls, repo stat, bitswap stat: examples now match real output
- drop the claim that --enc=json reports bytes. On the CLI, 'ipfs ls'
has a PostRun that prints the text table whatever --enc says, so no
JSON is produced there at all. Only the /api/v0/ls response is JSON,
and that part is true
- directories have no UnixFS Filesize, so they sort as 0 and tie with
empty files. They do not land strictly last, so stop saying they do
- changelog: a #### highlight with a TOC entry, kept short and pointing
at 'ipfs ls --help' for the details
- format sizes with strconv.FormatUint rather than fmt.Sprintf("%d")
lidel
left a comment
lidel
left a comment
There was a problem hiding this comment.
Thanks for this, @capricornusx. I pushed three commits to your branch rather than leaving a pile of inline comments (felt like cosmetic nits missed by your LLM, but intention was ok). Feature behaviour is unchanged.
-
4315e51 test(ls): make sort tests fail when sorting breaks
The--sort-sizetests couldn't fail. The unit tests copied the comparator into the test body, and the CLI fixtures (large.bin,medium.bin,small.bin) were already in size order alphabetically, so every ordering subtest passed with the feature disabled outright. ExtractedlsLinkByName/lsLinkBySizeso the tests hit shipped code, and renamed fixtures so the two orders disagree. -
078febb fix(ls): return 400 not 500 for bad flag combos
--sort-sizewith--streamor--size=falsemade/api/v0/lsanswer 500, so a client retrying on 5xx would retry a request that can never succeed.cmds.ErrClientmaps to 400. -
4485c12 docs: fix --human size examples and JSON claims
1K 234M 2Gis not what any of these print (humanize.Bytesgives1.2 kB,234 MB), though you inherited that fromrepo statandbitswap stat, so I fixed all three. Worth knowing:ipfs lshas aPostRunthat prints the text table whatever--encsays, so--enc=jsonyields no JSON on the CLI at all. That predates this PR, but the new help text promised otherwise. Also dropped "directories sort last", since with no UnixFSFilesizethey tie with empty files at 0.
|
Thanks! |
2 participants
