diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 171 |
1 files changed, 79 insertions, 92 deletions
@@ -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. |