Add documentation in the form of README.md

list-files

==========

*A simple tool for recursively listing files under a directory path, respecting 

various 'ignore'-file formats.*

'list-files' is a Python package and command-line tool for recursively listing 

files from a version control system (VCS) project. It does not require the VCS 

in question to be installed.

Unlike more general file finding tools like `find`, `list-files` will first 

determine if the target directory[^1] is under version control using 

a supported VCS system and if so, will echo a filtered list of the files within 

the directory.  If there is no detectable version control `list-files` falls 

back to listing all files under the given directory.

VCS detection is delegated to loader modules, which search backwards through 

the filesystem[^2] for indications of a VCS; some modules also use environment 

variable clues. If multiple VCSs are detected the one closest to the target 

directory is picked.

The file list is filtered using any relevant ignore-files for the VCS. For 

example if the files are within a git workspace, `list-files` will attempt to 

read git-ignore formated filter lists from `$GIT_DIR/info/exclude`, a file 

specified by the git config `core.excludesfile` and any

`.gitignore` files from each parent directory.

So far the supported VCSs are:

 * [Git](#Git Support)

[^1]: The target directory default to the current working directory if not 

given on the command line.

[^2]: When searching backwards the modules stop at mounted filesystem 

boundaries.

Git Support

-----------

Git repositories are detected by the presence of a file or directory named 

'.git' (`$GIT_DIR`)

Git ignore files are searched for at the following locations:

 * A `.gitignore` file in each ancestor of the target directory up to the top 

 	 of the repository workspace.

 * `$GIT_DIR/info/excludes`

 * A file named by the git config value `core.excludesfiles` which defaults to 

 	 the first found of:

   - `$XDG_CONFIG_HOME/git/ignore`

   - `$HOME/.config/git/ignore`

 * A `.gitignore` file in each scanned directory within the target directory.  

 	 (Directories that are excluded by a previous ignore file are not scanned.)

Exclude patterns from files named `.gitignore` are only applied to files and 

directories under the directory where the file was found.

Git configuration variables are searched for in the following files:

 * `$GIT_DIR/config`

 * `$HOME/.gitconfig`