diff options
| -rw-r--r-- | docs/reference/mpremote.rst | 28 | ||||
| -rw-r--r-- | tools/mpremote/tests/README.md | 15 |
2 files changed, 39 insertions, 4 deletions
diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst index ef23cd85c..32ca5c246 100644 --- a/docs/reference/mpremote.rst +++ b/docs/reference/mpremote.rst @@ -229,7 +229,7 @@ The full list of supported commands are: - ``ls`` to list the current directory - ``ls <dirs...>`` to list the given directories - ``cp [-rf] <src...> <dest>`` to copy files - - ``rm <src...>`` to remove files on the device + - ``rm [-r] <src...>`` to remove files or folders on the device - ``mkdir <dirs...>`` to create directories on the device - ``rmdir <dirs...>`` to remove directories on the device - ``touch <file..>`` to create the files (if they don't already exist) @@ -238,15 +238,35 @@ The full list of supported commands are: The ``cp`` command uses a convention where a leading ``:`` represents a remote path. Without a leading ``:`` means a local path. This is based on the convention used by the `Secure Copy Protocol (scp) client - <https://en.wikipedia.org/wiki/Secure_copy_protocol>`_. All other commands - implicitly assume the path is a remote path, but the ``:`` can be optionally - used for clarity. + <https://en.wikipedia.org/wiki/Secure_copy_protocol>`_. So for example, ``mpremote fs cp main.py :main.py`` copies ``main.py`` from the current local directory to the remote filesystem, whereas ``mpremote fs cp :main.py main.py`` copies ``main.py`` from the device back to the current directory. + The ``mpremote rm -r`` command accepts both relative and absolute paths. + Use ``:`` to refer to the current remote working directory (cwd) to allow a + directory tree to be removed from the device's default path (eg ``/flash``, ``/``). + Use ``-v/--verbose`` to see the files being removed. + + For example: + + - ``mpremote rm -r :libs`` will remove the ``libs`` directory and all its + child items from the device. + - ``mpremote rm -rv :/sd`` will remove all files from a mounted SDCard and result + in a non-blocking warning. The mount will be retained. + - ``mpremote rm -rv :/`` will remove all files on the device, including any + located in mounted vfs such as ``/sd`` or ``/flash``. After removing all folders + and files, this will also return an error to mimic unix ``rm -rf /`` behaviour. + + .. warning:: + There is no supported way to undelete files removed by ``mpremote rm -r :``. + Please use with caution. + + All other commands implicitly assume the path is a remote path, but the ``:`` + can be optionally used for clarity. + All of the filesystem sub-commands take multiple path arguments, so if there is another command in the sequence, you must use ``+`` to terminate the arguments, e.g. diff --git a/tools/mpremote/tests/README.md b/tools/mpremote/tests/README.md index 5b924d2fb..d1d77f1fb 100644 --- a/tools/mpremote/tests/README.md +++ b/tools/mpremote/tests/README.md @@ -4,11 +4,26 @@ This directory contains a set of tests for `mpremote`. Requirements: - A device running MicroPython connected to a serial port on the host. +- The device you are testing against must be flashed with a firmware of the same build + as `mpremote`. +- If the device has an SDcard or other vfs mounted, the vfs's filesystem must be empty + to pass the filesystem test. - Python 3.x, `bash` and various Unix tools such as `find`, `mktemp`, `sed`, `sort`, `tr`. +- To test on Windows, you can either: + - Run the (Linux) tests in WSL2 against a USB device that is passed though to WSL2. + - Use the `Git Bash` terminal to run the tests against a device connected to a COM + port. _Note:_ While the tests will run in `Git Bash`, several will throw false + positive errors due to differences in the way that TMP files are logged and and + several other details. To run the tests do: + $ cd tools/mpremote/tests $ ./run-mpremote-tests.sh +To run a single test do: + + $ ./run-mpremote-tests.sh test_filesystem.sh + Each test should print "OK" if it passed. Otherwise it will print "CRASH", or "FAIL" and a diff of the expected and actual test output. |