usage.rst

Usage

The basic usage syntax looks like this:

dotgit [flags] {action} [category [category]]

Where action is one of the actions listed below and category is one or more categories or groups to activate. If no categories are specified dotgit will automatically activate the common category as well as a category with your machine's hostname.

Using categories

When you run dotgit all of its actions will be limited to the categories that are activated. If you don't specify any categories the default behaviour is to activate the common category as well as a category with your machine's hostname (e.g. my-laptop).

When you run dotgit all the files in the filelist that are not part of the active categories will be ignored. You can run dotgit with two verbose flags -vv to see what categories are currently active.

Flags

.. option:: -h, --help

   Display a help message

.. option:: -v, --verbose

   Increase dotgit's verbosity level. Can be specified multiple times

   .. note::

      It is a good idea to run dotgit with at least one ``-v`` flag since no
      output will be generated by default (unless there is an error).

.. option:: --dry-run

   When specified dotgit won't make any changes to the filesystem. Useful when
   running with ``-v`` to see what dotgit would do if you run a command

.. option:: --hard

   Activates "hard" mode where files are copied rather than symlinked. Useful
   if symlinking isn't an option or if you want the dotfiles to live on the
   machine independently of the dotgit repo.

   .. note::

      If you want to use hard mode you need to specify it every time you run
      dotgit

Actions

.. option:: init

   Initializes a new dotgit repository. Creates an empty filelist and also
   runs ``git init`` if the repo is not a valid git repository. You only need
   to run this once (when you set up a new dotgit repo). Running this multiple
   times has no effect.

.. option:: update

   Updates the dotgit repository. Run this after you made changes to your
   filelist or if you want to add the changes to non-symlinked files to your
   repo (e.g. encrypted files). This will save your dotfiles from your home
   folder in your dotgit repo, and also set up the links/copies to your
   dotfiles repo as needed (runs a ``restore`` operation after updating).

   .. note::

      When you run the ``update`` command dotgit will replace any files in the
      repo with those in your home folder. Make sure to run the ``restore``
      command first on a new machine otherwise you might end up inadvertently
      replacing files in your repo.

.. option:: restore

   Links or copies files from your dotgit repo to your home folder. Use this if
   you want to restore your dotfiles to a new machine.

.. option:: clean

   Removes all the dotfiles managed by dotgit from your home folder (run first
   with the ``-v --dry-run`` flags to see what dotgit plans on doing).

.. option:: diff

   Prints which changes have been made to your dotfiles repo since the last
   commit.

.. option:: commit

   This will generate a git commit with all the current changes in the repo and
   will ask you if you want to push the commit to a remote (if one is
   configured).

.. option:: passwd

   Allows you to change your encryption password.