===========================================
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