mirror of
https://github.com/gryf/mc_adbfs.git
synced 2025-12-18 12:00:19 +01:00
155 lines
4.5 KiB
ReStructuredText
155 lines
4.5 KiB
ReStructuredText
===========================================
|
|
Midnight Commander adbfs external fs plugin
|
|
===========================================
|
|
|
|
This is Midnight Commander extfs plugin for browsing Android device through
|
|
``adb`` interface written in Python.
|
|
|
|
|
|
Rquirements
|
|
===========
|
|
|
|
* Python 3.x (tested on 3.5.4, 3.6 and 3.7)
|
|
* ``adb`` installed and in ``$PATH`` or provided via the config file
|
|
* An Android device or emulator preferably rooted
|
|
* ``busybox`` (``toolbox``, ``toybox``) installed and available in the path on
|
|
the device
|
|
|
|
Make sure, that issuing from command line:
|
|
|
|
.. code:: shell-session
|
|
|
|
$ adb shell busybox ls
|
|
$ # or in case of no PATH adb placement
|
|
$ /path/to/adb shell busybox ls
|
|
|
|
it should display files from root directory on the device.
|
|
|
|
|
|
Features
|
|
========
|
|
|
|
* Listing the directory with (default), or without skipping system dirs
|
|
(``acct``, ``dev``, ``proc``, etc)
|
|
* Copying files from and to the device
|
|
* Creating directories
|
|
* Removing files and directories
|
|
* Symbolic links in lists are corrected to be relative to the file system
|
|
* Symbolic links also point to the right target, skipping intermediate links
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
Copy adbfs into ``~/.local/share/mc/extfs.d/`` directory and make it executable
|
|
if needed.
|
|
|
|
|
|
Usage
|
|
=====
|
|
|
|
To use it, just issue:
|
|
|
|
.. code:: shell-session
|
|
|
|
$ cd adbfs://
|
|
|
|
under MC - after some time you should see the files and directories on your
|
|
device. For convenience you can add a bookmark (accessible under CTRL+\\) for
|
|
fast access. The time is depended on how many files and directories you have on
|
|
your device and how fast it is :)
|
|
|
|
|
|
Configuration
|
|
=============
|
|
|
|
You can configure behaviour of this plugin using ``.ini`` file located under
|
|
``$XDG_CONFIG_HOME/mc/adbfs.ini`` (which usually is located under
|
|
``~/.config/mc/adbfs.ini``), and have default values, like:
|
|
|
|
.. code:: ini
|
|
|
|
[adbfs]
|
|
debug = false
|
|
dirs_to_skip = ["acct", "charger", "d", "dev", "proc", "sys"]
|
|
suppress_colors = false
|
|
root =
|
|
adb_command = adb
|
|
adb_connect =
|
|
try_su = false
|
|
|
|
where:
|
|
|
|
* ``debug`` will provide a little bit more verbose information, useful for
|
|
debugging
|
|
* ``dirs_to_skip`` list of paths to directories which will be skipped during
|
|
reading. If leaved empty, or setted to empty list (``[]``) will read
|
|
everything (slow!)
|
|
* ``suppress_colors`` this option will make ``busybox`` not to display colors,
|
|
helpful, if ``busybox ls`` is configured to display colors by default. Does
|
|
not affect ``toolbox`` or ``toybox``.
|
|
* ``root`` root directory to read. Everything outside of that directory will be
|
|
omitted. That would be the fastest way to access certain location on the
|
|
device. Note, that ``dirs_to_skip`` still apply inside this directory.
|
|
* ``adb_command`` absolute or relative path to ``adb`` command. ``~/`` or
|
|
environment variables are allowed.
|
|
* ``adb_connect`` specifies if connection to specific device needs to be
|
|
performed before accessing shell. It is useful for *adb over network*
|
|
feature. Typical value here is a device IP address with optional port, which
|
|
defaults to 5555.
|
|
* ``try_su`` specifies whether or not to try to detect if ``su`` command is
|
|
available and usable.
|
|
|
|
|
|
Contribution
|
|
============
|
|
|
|
There is a ``Makefile`` in the top directory, which is basic helper for running
|
|
the tests. Please use it, and adapt/add tests for provided fixes/functionality.
|
|
The reason why `tox`_ wasn't used is, that there is no ``setup.py`` file, and
|
|
it's difficult to install simple script, which isn't a python module (python
|
|
interpreter will refuse to import module without ``.py`` extension).
|
|
|
|
It requires GNU ``make`` program, and also ``virtualenv``. Using it is simple
|
|
as running following command:
|
|
|
|
.. code:: shell-session
|
|
|
|
$ make
|
|
|
|
it will run `py3` and `flake8` jobs to check it against the code. For
|
|
running tests against Python 3:
|
|
|
|
.. code:: shell-session
|
|
|
|
$ make py3
|
|
|
|
or flake 8:
|
|
|
|
.. code:: shell-session
|
|
|
|
$ make flake8
|
|
|
|
Exit status on any of those means that test fail. Appropriate message/traceback
|
|
will also be visible.
|
|
|
|
|
|
Limitations
|
|
===========
|
|
|
|
* Initial listing might be slow. Depending on how fast the device is, how many
|
|
files are on the device and so on
|
|
* Some filenames might be still inaccessible for operating
|
|
* All files operations which needs root privileges will fail (for now)
|
|
* The implementation is experimental and it's by now working with mine device;
|
|
while it might not work with yours
|
|
|
|
|
|
License
|
|
=======
|
|
|
|
This software is licensed under 3-clause BSD license. See LICENSE file for
|
|
details.
|
|
|
|
.. _tox: https://tox.readthedocs.io
|