Add `mpremote fs tree` command to show a tree of the device's files. #17112

Josverl · 2025-04-10T17:06:00Z

Summary

This PR adds a new command to mpremote that displays the file system of a connected device in a tree format.

While working on mpremote rm -r I developed a desire to see a tree-view of files on the device.
I build a PoC for this and asked for feedback
where there appears to be a common need for this.

The mpremote fs tree command :

Shows treeview from current path or specified path
uses the graph chars ("├── ", "└── ") ( not configurable)
options:
- -v/--verbose adds the serial device name to the top of the tree
- -s/--size add a (human readable) size to the files. ( not using -h as that )

This PR also fixes a limitation where ls can be run without specifying a path, but this would result in an error if an option was specified.
As tree also uses the same logic I wanted to fix this for both commands.

Example tree view:

$ mpremote resume tree -sv /
tree :/
:/ on /dev/ttyACM0
├── [  10B] a.py
├── [ 1.9K] b.py
├── backup
│   ├── [  10B] a.py
│   ├── [ 1.9K] b.py
│   ├── foo
│   │   ├── [   0B] aa.py
│   │   └── [   0B] ba.py
│   └── lib
│       ├── [   0B] bar.py
│       └── [   0B] foo.py
├── [   0B] bar.py
├── foo
│   ├── [   0B] aa.py
│   └── [   0B] ba.py
├── [   0B] foo.py
├── lib
│   ├── [   0B] bar.py
│   └── [   0B] foo.py
└── ramdisk
    ├── [   0B] bar.py
    ├── [   0B] foo.py
    └── lib
        ├── [   0B] lib_bar.py
        └── [   0B] lib_foo.py

Testing

Automated tests for valid and error cases have been added, but can only be verified on unix based systems.
The -v option cannot be tested reliably with the .exp output approach as devices can, and will, be assigned to different port names. So this has been omitted from automated tests.

Note that there is now 3x duplication of the ramdisk.py script across multiple test scripts.
It would be best to reduce this to a single file and use it in all tests.

Manual testing:

port	WSL2/ubuntu	Windows
stm32	PASS	PASS
samd	PASS	PASS
esp32	PASS	PASS

Documentation

Documentation and samples for the fs tree command have been added to the mpremote doc page.
A few sub sections have been added to the fs section to improve readability,
A few paragraphs have been moved to a more appropriate location to better fit this structure.

codecov · 2025-04-10T17:08:12Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.54%. Comparing base (6406afb) to head (968aaf6).
Report is 21 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #17112   +/-   ##
=======================================
  Coverage   98.54%   98.54%           
=======================================
  Files         169      169           
  Lines       21890    21898    +8     
=======================================
+ Hits        21572    21580    +8     
  Misses        318      318

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2025-04-10T17:15:33Z

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

dpgeorge · 2025-04-24T12:50:15Z

This is great, thank you!

-s/--size add a (human readable) size to the files. ( not using -h as that )

Honestly, I find non-human-readable sizes, ie just byte sizes, more readable. Because the size/length of the number shows how big the file is, and it's much easier to spot small/big files when -h is not used.

So, maybe add a -h option that needs to be explicitly specified, to match the unix tree command?

Josverl · 2025-04-24T16:43:10Z

Should be no problem to add both -s and -h

Josverl · 2025-04-25T21:10:17Z

mpremote tree now takes either --size/-s or --human und uses the corresponding size format.

Details

$ mpremote tree -s
tree :
:/
└── boards
    ├── [          46] 96b_carbon.conf
    ├── [         163] bbc_microbit_v2.conf
    ├── [          97] beagleconnect_freedom.conf
    ├── [          77] disco_l475_iot1.conf
    ├── [         264] frdm_k64f.conf
    ├── [         122] frdm_kw41z.conf
    ├── [         206] mimxrt1050_evk.conf
    ├── [          33] mimxrt685_evk_cm33.conf
    ├── [         273] nrf52840dk_nrf52840.conf
    ├── [         146] nucleo_h743zi.conf
    ├── [         467] nucleo_h743zi.overlay
    ├── [         131] nucleo_wb55rg.conf
    ├── [         172] qemu_cortex_m3.conf
    ├── [         172] qemu_x86.conf
    ├── [          81] reel_board.conf
    └── [          50] rv32m1_vega_ri5cy.conf

$ mpremote tree --human
tree :
:/
└── boards
    ├── [    46 B] 96b_carbon.conf
    ├── [   163 B] bbc_microbit_v2.conf
    ├── [    97 B] beagleconnect_freedom.conf
    ├── [    77 B] disco_l475_iot1.conf
    ├── [   264 B] frdm_k64f.conf
    ├── [   122 B] frdm_kw41z.conf
    ├── [   206 B] mimxrt1050_evk.conf
    ├── [    33 B] mimxrt685_evk_cm33.conf
    ├── [   273 B] nrf52840dk_nrf52840.conf
    ├── [   146 B] nucleo_h743zi.conf
    ├── [   467 B] nucleo_h743zi.overlay
    ├── [   131 B] nucleo_wb55rg.conf
    ├── [   172 B] qemu_cortex_m3.conf
    ├── [   172 B] qemu_x86.conf
    ├── [    81 B] reel_board.conf
    └── [    50 B] rv32m1_vega_ri5cy.conf

docs/reference/mpremote.rst

tools/mpremote/mpremote/main.py

Josverl · 2025-04-26T21:43:40Z

updated and rebased

tools/mpremote/mpremote/main.py

tools/mpremote/mpremote/commands.py

Josverl · 2025-04-27T14:53:56Z

@dpgeorge ,
on the whole I do not like the esthetics an usability of identing the directories / folders with no size reported by ilistdir() ( 100% in my testing)

I propose to implement option 1) below

1) not outlined - no []

│   ├── [      172]qemu_cortex_m3.conf
│   ├── [      172]qemu_x86.conf
│   ├── [       81]reel_board.conf
│   └── [       50]rv32m1_vega_ri5cy.conf
├── foo
│   ├── [        0]aa.py
│   └── [        0]ba.py
├── [        0]foo.py
└── lib
    ├── aioble
    │   ├── [      602]__init__.mpy
    │   ├── [     2465]central.mpy
    │   ├── [     4116]client.mpy
    │   ├── [      763]core.mpy

2) outlined - no []

│   ├── [      172]qemu_cortex_m3.conf
│   ├── [      172]qemu_x86.conf
│   ├── [       81]reel_board.conf
│   └── [       50]rv32m1_vega_ri5cy.conf
├──            foo
│   ├── [        0]aa.py
│   └── [        0]ba.py
├── [        0]foo.py
└──            lib
    ├──            aioble
    │   ├── [      602]__init__.mpy
    │   ├── [     2465]central.mpy

3) outlined , []

│   ├── [      172]qemu_x86.conf
│   ├── [       81]reel_board.conf
│   └── [       50]rv32m1_vega_ri5cy.conf
├── [           ]foo
│   ├── [        0]aa.py
│   └── [        0]ba.py
├── [        0]foo.py
└── [           ]lib
    ├── [           ]aioble
    │   ├── [      602]__init__.mpy
    │   ├── [     2465]central.mpy
    │   ├── [     4116]client.mpy
    │   ├── [      763]core.mpy

4) outlined , [ 0]

│   ├── [      172]qemu_cortex_m3.conf
│   ├── [      172]qemu_x86.conf
│   ├── [       81]reel_board.conf
│   └── [       50]rv32m1_vega_ri5cy.conf
├── [        0]foo
│   ├── [        0]aa.py
│   └── [        0]ba.py
├── [        0]foo.py
└── [        0]lib
    ├── [        0]aioble
    │   ├── [      602]__init__.mpy
    │   ├── [     2465]central.mpy
    │   ├── [     4116]client.mpy

tools/mpremote/mpremote/commands.py

mattytrentini · 2025-04-28T01:19:24Z

@dpgeorge , on the whole I do not like the esthetics an usability of identing the directories / folders with no size reported by ilistdir() ( 100% in my testing)

I propose to implement option 1) below

FWIW I prefer option 1) too.

A small request though: Could you add two spaces after the closing square bracket (as unix tree does)? Dramatically improves readability IMO.

I prefer the human readable output, though I note that it's different to unix tree (which is always 4 chars, I believe).

In any case, thanks @Josverl! This is a handy addition.

Josverl · 2025-04-28T01:43:31Z

@mattytrentini This was the reasoning

format	unix tree	mpremote tree	notes
--size	12	9	smaller files on micropython
--human	4	6	allow for one decimal `[ 13.8K]` (for those smaller files)

And one additional space coming up

Add `mpremote fs tree` command to show a tree of the device's files. Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

Josverl force-pushed the mpr/fs_tree branch from a4622e4 to 4b737c3 Compare April 10, 2025 21:57

Josverl marked this pull request as ready for review April 10, 2025 22:40

dpgeorge added this to the release-1.26.0 milestone Apr 14, 2025

dpgeorge added the tools Relates to tools/ directory in source, or other tooling label Apr 14, 2025

Josverl force-pushed the mpr/fs_tree branch from 1239d57 to 0b43bd1 Compare April 25, 2025 21:02

dpgeorge reviewed Apr 26, 2025

View reviewed changes

docs/reference/mpremote.rst Outdated Show resolved Hide resolved

tools/mpremote/mpremote/main.py Show resolved Hide resolved

tools/mpremote/mpremote/main.py Outdated Show resolved Hide resolved

Josverl force-pushed the mpr/fs_tree branch 2 times, most recently from b680f54 to cf8fecf Compare April 26, 2025 21:42

dpgeorge reviewed Apr 27, 2025

View reviewed changes

Josverl force-pushed the mpr/fs_tree branch 2 times, most recently from 234a834 to abf9829 Compare April 27, 2025 21:08

dpgeorge reviewed Apr 28, 2025

View reviewed changes

tools/mpremote/mpremote/commands.py Outdated Show resolved Hide resolved

tools/mpremote/mpremote/commands.py Outdated Show resolved Hide resolved

tools/mpremote/mpremote/commands.py Outdated Show resolved Hide resolved

Josverl force-pushed the mpr/fs_tree branch 3 times, most recently from 3056b5b to a1d4e1d Compare April 28, 2025 01:36

Josverl force-pushed the mpr/fs_tree branch from a1d4e1d to 85af926 Compare April 28, 2025 01:47

Josverl added 3 commits May 2, 2025 17:11

tools/mpremote: Add 'fs tree' command.

88d5947

Add `mpremote fs tree` command to show a tree of the device's files. Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

tools/mpremote/tests: Add tests for 'fs tree' command.

e2d0e49

Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

docs/mpremote.rst: Document the 'fs tree' command.

968aaf6

Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

Josverl force-pushed the mpr/fs_tree branch from 85af926 to 968aaf6 Compare May 2, 2025 15:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `mpremote fs tree` command to show a tree of the device's files. #17112

Add `mpremote fs tree` command to show a tree of the device's files. #17112

Josverl commented Apr 10, 2025 •

edited

Loading

codecov bot commented Apr 10, 2025 •

edited

Loading

github-actions bot commented Apr 10, 2025

dpgeorge commented Apr 24, 2025

Josverl commented Apr 24, 2025

Josverl commented Apr 25, 2025

Josverl commented Apr 26, 2025

Josverl commented Apr 27, 2025

mattytrentini commented Apr 28, 2025 •

edited

Loading

Josverl commented Apr 28, 2025

Add mpremote fs tree command to show a tree of the device's files. #17112

Are you sure you want to change the base?

Add mpremote fs tree command to show a tree of the device's files. #17112

Conversation

Josverl commented Apr 10, 2025 • edited Loading

Summary

Testing

Documentation

codecov bot commented Apr 10, 2025 • edited Loading

Codecov Report

github-actions bot commented Apr 10, 2025

dpgeorge commented Apr 24, 2025

Josverl commented Apr 24, 2025

Josverl commented Apr 25, 2025

Josverl commented Apr 26, 2025

Josverl commented Apr 27, 2025

1) not outlined - no []

2) outlined - no []

3) outlined , []

4) outlined , [ 0]

mattytrentini commented Apr 28, 2025 • edited Loading

Josverl commented Apr 28, 2025

Add `mpremote fs tree` command to show a tree of the device's files. #17112

Add `mpremote fs tree` command to show a tree of the device's files. #17112

Josverl commented Apr 10, 2025 •

edited

Loading

codecov bot commented Apr 10, 2025 •

edited

Loading

mattytrentini commented Apr 28, 2025 •

edited

Loading