Renames README

1 files changed, 118 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a613a76
--- /dev/null
+++ b/README.md
@@ -0,0 +1,118 @@
+Metadot: modular dotfile management
+===================================
+
+Metadot allows you to easilly manage and reuse existing dotfiles repositories
+by simply cloning then to your `~/.dotfiles/modules` and renaming a few files.
+
+By being modular, it's possible to create modules for specific applications
+(vim, mutt, emacs, git, etc). By using git submodules or subtrees, one can even
+create her own dotfile collection.
+
+It was inspired by [holman does dotfiles](https://github.com/holman/dotfiles)
+and many other initiatives but with a modular design to ease dotfile sharing as
+the `metadot` code is split from the dotfiles' folder.
+
+Instalation
+-----------
+
+Get the code:
+
+    git clone https://git.fluxo.info/metadot
+
+Then check the source integrity of the latest release:
+
+    /usr/bin/git -C metadot verify-commit HEAD
+
+Note that `/usr/bin/git` is called to avoid any other `git` wrappers or aliases
+you might have available on your shell.
+
+Save the metadot repository anywhere but make sure it's available in your `$PATH`.
+I'm my config I use `~/apps/metadot`.
+
+Then get some modules. You can get the whole standard module collection with
+
+    metadot clone https://git.fluxo.info/rhatto/dotfiles
+
+Or simply using
+
+    metadot clone default
+
+Modules names as `dotfiles` have a special meaning and are handled like collections
+and are cloned directly as `~/.dotfiles`. After cloning, you can check the current
+dotfiles revision using
+
+    metadot version
+
+Third-party collections will hardly suit your needs, so you can fetch individual
+modules:
+
+    metadot clone https://git.fluxo.info/rhatto/dotfiles/vim
+
+Or even start your own:
+
+    metadot create vim
+
+In both cases your `vim` module will be available at `~/.dotfiles/modules/vim`.
+
+You can use just one collection at a time. While you can mixed a collection with
+individual modules, it's more sane to just start your own collection and keep
+modules as git submodules or subtrees.
+
+Usage
+-----
+
+The full list of commands is available with `metadot usage`. You'll probably want
+to start with the following.
+
+List existing modules:
+
+    metadot ls
+
+Load a module:
+
+    metadot load <module>
+
+Load all modules:
+
+    metadot load --all
+
+Backups are made whenever a module is loaded.
+
+Layout
+------
+
+- `~/.dotfiles`: where all dotfiles modules are stored
+- `~/.backups`: backups of old config files
+- `~/.custom`: some modules use this folder for custom configuration overriding default parameters
+
+Module format
+-------------
+
+Modules rest at ~/.dotfiles/modules and can be git submodules or subtrees. File format is:
+
+    [path/]<name>[.dot][.link]
+
+Which means files
+
+- with a `.link` extension are linked at `$HOME`.
+- with a `.dot.link` extension are converted to a dotfile: `vimrc.dot.link` is linked as `~/.vimrc`.
+- with other extensions are ignored.
+
+Also,
+
+- file structure is preserved: `apps/scripts.link` is linked as `$HOME/apps/scripts`.
+- nested structures are allowed: `config.dot/awesome.link` is linked as `$HOME/.config/awesome`.
+
+See also
+--------
+
+* http://dotshare.it
+* http://dotfiles.org
+* https://dotfiles.github.io
+* https://wiki.archlinux.org/index.php/Dotfiles
+* http://www.madewithtea.com/dotfiles-are-your-digital-backpack.html
+
+Contact
+-------
+
+Comments and patches: rhatto at riseup.net