aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md171
1 files changed, 79 insertions, 92 deletions
diff --git a/README.md b/README.md
index 52d03ff..a9db0ea 100644
--- a/README.md
+++ b/README.md
@@ -66,179 +66,166 @@ The aim is for this information to be sufficient for use. At some point
I'll write a manpage, but do file a bug if any of the usage information
is inaccurate or misleading.
-## A Quick Example
+## Interface
-
-
-
-
-
-
-Interface
----------
-
-``-a, --add <file...>``
+`-a, --add <file...>`
Add dotfile(s) to the repository.
-``-c, --check``
+`-c, --check`
Check for missing or unsynced dotfiles.
-``-l, --list``
+`-l, --list`
List currently managed dotfiles, one per line.
-``-r, --remove <file...>``
+`-r, --remove <file...>`
Remove dotfile(s) from the repository.
-``-s, --sync [file...]``
- Update dotfile symlinks. You can overwrite colliding files with ``-f`` or
- ``--force``. All dotfiles are assumed if you do not specify any files to
+`-s, --sync [file...]`
+ Update dotfile symlinks. You can overwrite colliding files with `-f` or
+ `--force`. All dotfiles are assumed if you do not specify any files to
this command.
-``-m, --move <path>``
+`-m, --move <path>`
Move dotfiles repository to another location, updating all symlinks in the
process.
-For all commands you can use the ``--dry-run`` option, which will print actions
+For all commands you can use the `--dry-run` option, which will print actions
and won't modify anything on your drive.
-Installation
-------------
+## Installation
-To install dotfiles, simply: ::
+To install dotfiles, simply:
$ pip install dotfiles
-Or, if you absolutely must: ::
+Or, if you absolutely must:
$ easy_install dotfiles
But, you really shouldn't do that.
If you want to work with the latest version, you can install it from `the
-repository`_::
+repository`_:
$ git clone https://github.com/jbernard/dotfiles
$ cd dotfiles
$ ./bin/dotfiles --help
-Examples
---------
+## Examples
-To install your dotfiles on a new machine, you might do this: ::
+To install your dotfiles on a new machine, you might do this:
- $ git clone https://github.com/me/my-dotfiles Dotfiles
- $ dotfiles --sync
+ $ git clone https://github.com/me/my-dotfiles Dotfiles
+ $ dotfiles --sync
-To add '~/.vimrc' to your repository: ::
+To add '~/.vimrc' to your repository:
- $ dotfiles --add ~/.vimrc (relative paths work also)
+ $ dotfiles --add ~/.vimrc (relative paths work also)
-To make it available to all your hosts: ::
+To make it available to all your hosts:
- $ cd ~/Dotfiles
- $ git add vimrc
- $ git commit -m "Added vimrc, welcome aboard!"
- $ git push
+ $ cd ~/Dotfiles
+ $ git add vimrc
+ $ git commit -m "Added vimrc, welcome aboard!"
+ $ git push
-You get the idea. Type ``dotfiles --help`` to see the available options.
+You get the idea. Type `dotfiles --help` to see the available options.
-Configuration
--------------
+## Configuration
You can choose to create a configuration file to store personal customizations.
-By default, ``dotfiles`` will look for ``~/.dotfilesrc``. You can change this
-with the ``-C`` flag. An example configuration file might look like: ::
-
- [dotfiles]
- repository = ~/Dotfiles
- ignore = [
- '.git',
- '.gitignore',
- '*.swp']
- externals = {
- '.bzr.log': '/dev/null',
- '.uml': '/tmp'}
+By default, `dotfiles` will look for `~/.dotfilesrc`. You can change this
+with the `-C` flag. An example configuration file might look like:
+
+ [dotfiles]
+ repository = ~/Dotfiles
+ ignore = [
+ '.git',
+ '.gitignore',
+ '*.swp']
+ externals = {
+ '.bzr.log': '/dev/null',
+ '.uml': '/tmp'}
You can also store your configuration file inside your repository. Put your
-settings in ``.dotfilesrc`` at the root of your repository and ``dotfiles`` will
-find it. Note that ``ignore`` and ``externals`` are appended to any values
+settings in `.dotfilesrc` at the root of your repository and `dotfiles` will
+find it. Note that `ignore` and `externals` are appended to any values
previously discovered.
Prefixes
--------
Dotfiles are stored in the repository with no prefix by default. So,
-``~/.bashrc`` will link to ``~/Dotfiles/bashrc``. If your files already have a
-prefix, ``.`` is common, but I've also seen ``_``, then you can specify this
-in the configuration file and ``dotfiles`` will do the right thing. An example
-configuration in ``~/.dotfilesrc`` might look like: ::
+`~/.bashrc` will link to `~/Dotfiles/bashrc`. If your files already have a
+prefix, `.` is common, but I've also seen `_`, then you can specify this
+in the configuration file and `dotfiles` will do the right thing. An example
+configuration in `~/.dotfilesrc` might look like:
- [dotfiles]
- prefix = .
+ [dotfiles]
+ prefix = .
Externals
---------
-You may want to link some dotfiles to external locations. For example, ``bzr``
-writes debug information to ``~/.bzr.log`` and there is no easy way to disable
-it. For that, I link ``~/.bzr.log`` to ``/dev/null``. Since ``/dev/null`` is
+You may want to link some dotfiles to external locations. For example, `bzr`
+writes debug information to `~/.bzr.log` and there is no easy way to disable
+it. For that, I link `~/.bzr.log` to `/dev/null`. Since `/dev/null` is
not within the repository, this is called an external. You can have as many of
these as you like. The list of externals is specified in the configuration
-file: ::
+file:
- [dotfiles]
- externals = {
- '.bzr.log': '/dev/null',
- '.adobe': '/tmp',
- '.macromedia': '/tmp'}
+ [dotfiles]
+ externals = {
+ '.bzr.log': '/dev/null',
+ '.adobe': '/tmp',
+ '.macromedia': '/tmp'}
Ignores
-------
If you're using a VCS to manage your repository of dotfiles, you'll want to
-tell ``dotfiles`` to ignore VCS-related files. For example, I use ``git``, so
-I have the following in my ``~/.dotfilesrc``: ::
+tell `dotfiles` to ignore VCS-related files. For example, I use `git`, so
+I have the following in my `~/.dotfilesrc`:
- [dotfiles]
- ignore = [
- '.git',
- '.gitignore',
- '*.swp']
+ [dotfiles]
+ ignore = [
+ '.git',
+ '.gitignore',
+ '*.swp']
-Any file you list in ``ignore`` will be skipped. The ``ignore`` option supports
+Any file you list in `ignore` will be skipped. The `ignore` option supports
glob file patterns.
Packages
--------
-Many programs store their configuration in ``~/.config``. It's quite cluttered
+Many programs store their configuration in `~/.config`. It's quite cluttered
and you probably don't want to keep all its content in your repository. For this
-situation you can use the ``packages`` setting::
+situation you can use the `packages` setting:
[dotfiles]
packages = ['config']
-This tells ``dotfiles`` that the contents of the ``config`` subdirectory of
-your repository must be symlinked to ``~/.config``. If for example you have a
-directory ``config/awesome`` in your repository, it will be symlinked to
-``~/.config/awesome``.
+This tells `dotfiles` that the contents of the `config` subdirectory of
+your repository must be symlinked to `~/.config`. If for example you have a
+directory `config/awesome` in your repository, it will be symlinked to
+`~/.config/awesome`.
This feature allows one additional level of nesting, but further subdirectories
-are not eligible for being a package. For example, ``config`` is valid, but
-``config/transmission`` is not valid. Arbitrary nesting is a feature under
+are not eligible for being a package. For example, `config` is valid, but
+`config/transmission` is not valid. Arbitrary nesting is a feature under
current consideration.
At the moment, packages can not be added or removed through the command line
interface. They must be constructed and configured manually. Once this is
-done, ``sync``, ``list``, ``check``, and ``move`` will do the right thing.
-Support for ``add`` and ``remove`` is a current TODO item.
+done, `sync`, `list`, `check`, and `move` will do the right thing.
+Support for `add` and `remove` is a current TODO item.
Contribute
----------
-If you'd like to contribute, simply fork `the repository`_, commit your changes,
-make sure tests pass, and send a pull request. Go ahead and add yourself to
-AUTHORS_ or I'll do it when I merge your changes.
-
-.. _`the repository`: https://github.com/jbernard/dotfiles
-.. _AUTHORS: https://github.com/jbernard/dotfiles/blob/master/AUTHORS.md
+If you'd like to contribute, simply fork [the
+repository](https://github.com/jbernard/dotfiles), commit your changes, make
+sure tests pass, and send a pull request. Go ahead and add yourself to
+[AUTHORS](https://github.com/plasticboy/vim-markdown/issues/408) AUTHORS_ or
+I'll do it when I merge your changes.