What is this?
=============
mc-extfs-adb is a virtual file system plugin for the famous Midnight Commander
(http://www.midnight-commander.org/) on Linux only. It utilizes Bash and ADB
to give access to an Android device connected via USB. For some reason, the
original developer decided to use a specific version of Busybox for this; a.o.
this ensures it works the same way on all devices. Don't worry: this specific
busybox binary will be automatically pushed to your device's "/data/local"
directory, where it shouldn't break anything.

Requirements
============
* Linux on your computer
* Bash (comes with almost every Linux installation by default)
* Midnight Commander of course
* ADB tools (either via the Android SDK, or a minimal installation, see
  http://android.stackexchange.com/questions/42474/16575

Installation
============
Simply copy the *files* contained in the "install" directory to...

* /usr/lib/mc/extfs.d     (Debian, Ubuntu, Mint, and related)
* /usr/libexec/mc/extfs.d (Fedora, and probably ReadHat, Mandriva, SuSE,
                           and others as well)

The following files need to be copied there:

* adb+           (see also below)
* busybox.armv5
* extfs          (see doc/README.txt)

Usage
=====
Start "mc", and then simply "cd adb://" (or Alt-C, "adb://"). Initialization will
take quite a while, so do not get shocked: once that step is finished, you can
browse the filesystem quite speedy.

On its very first use, the vfs will check if its busybox was already copied to
the device (/data/local/busybox). If not, it will do so. If you see a message
for a failed "chmod", that means the ADB daemon on your device is not running
in root mode. If you do not want to browse system-protected directories, you
don't need to worry: Simply exit mc, start it again, and you will be fine: on
your next try, this step will be skipped. (hint: Ctrl-X a should do as well)

Next comes what makes the process seeming slow: the VFS caches the entire directory
structure. Once that is done, navigating the directory tree is astonishingly fast:
Basically, the device is not accessed anymore for that, but the cached structure
is used. This saves a lot of ADB overhead, and makes navigation that fast.

You can access files (reading/writing, copying, and all) like you are used with
Midnight Commander (see doc/README.txt for details). Note however that they are
dealt with as being from a non-local source: if you e.g. want to display a photo,
the file will first be copied to a temporary directory, and the viewer is invoked
on that copy then. So no slideshow this way.

The root way
============
By default, the ADB daemon on your device will not run in root mode. This should
theoretically be accomplished by invoking "adb root" -- but that will fail on
most devices, giving the error message "adbd cannot run as root in production builds",
which is for security reasons ("root mode" is reserved for development). If you want
to browse syste,-protected directories (such as e.g. "/data/data") with mc-extfs-adb,
you have multiple choices -- provided your device is rooted:

fake it
-------
You can used a modified version of adb+ I've created, located in the adb_rootfake
directory. This will use "su" to create the file-system cache (so you will have to
approve this access on your device's super-user app, such as SuperSU oder SuperUser,
which will prompt you for it). This works fine for browsing the directory tree
(from the cache, so no problem), and for viewing text files (which then is done
via "adb shell su -c" as well) -- but will fail for copying protected stuff (which
is done via "adb pull" / "adb push", where we cannot use "su"). So it's a little
limited, but better than nothing :)

force it
--------
Chainfire has created an app called "adb-Insecure", which can be found at XDA
(http://www.xda-developers.com/android/run-adbd-in-root-mode-with-adbd-insecure/)
and in the Playstore (https://play.google.com/store/apps/details?id=eu.chainfire.adbd).
Using this app on your Android device, you can force its ADB daemon into root mode.
This should enable you to do "all things root": not only browsing the file system
and investigating text files, but to copy/move/edit everything MC is capable of.
No need for the modified adb+ in this case; but, of course, this as well
requires your device to be rooted (and you must have the "rooted mode" enabled
with this app).

Credits
=======
Most credits go to the original author, Volodymyr M. Lisivka  <vlisivka@gmail.com>.
I took his original sources from this post:
http://forum.cyanogenmod.com/topic/23637-browse-phone-file-system-using-midnight-commander-linux-only/

Alternatives
============
If you want the file system of your Android device being visible outside of MC
as well, I recommend you take a look into "adb-rootless" (see:
https://github.com/spion/adbfs-rootless). This tool runs as "FUSE driver"
(File System in User Space, i.e. no root required on the Linux end to mount /
unmount the file system). Depending on the ADB daemon on the device, this
might offer you root access on the Android side as well: the term "rootless"
here refers to the two facts that neither your Android device *has* to be rooted,
nor you need root access on your Linux box to mount it.

You will notice a few differences compared to mc-extfs-adb:

+ it is usable independenty from MC
+ no busybox being pushed to the device
+ the "drive" will be available a little faster (it's not reading in the complete
  directory structure on init)
~ navigating the file system will be a little slower (again, no initial caching)
+ as it appears as "normal directory" to MC, things like slideshows are possible
* you have to mount it before cd'ing into
- you have to unmount it before removing your device to prevent data loss
  (while mc-extfs-adb works "on-the-fly" in this context)

Handling is quite easy. Initially, you have to create a mount-point (say, /mnt/droid).
Then you can simply "adbfs /mnt/droid" to mount, and "fusermount -u /mnt/droid" to
unmount (which you should not forget before removing your device). Hint: edit your
~/.bashrc (or wherever you stored your aliases) to include:

alias mdroid="adbfs /mnt/droid"
alias udroid="fusermount -u /mnt/droid"
alias umountdroid="sudo umount /mnt/droid"

(the last command is just-in-case the normal umount fails). Saves you some typing,
and is easier to remember. After the aliases have been reloaded (new shell, or
simply sourcing it into the current one), you can mount your currently connected
Android device with a simple "mdroid", and unmount it with a simple "udroid".

You've got the choice!
