dotfiles -- manage your dotfiles in git

This file should reside as ~/.dotfiles.sh.  That makes it possible
to revision and upgrade itself. An user can then install to
'/usr/local/bin' or any other directory.

After that the 'init' command sets up '~/.dotfiles' as bare git
repository where configuration files will be stored. There will be no
'master' branch but a "$USER@$HOSTNAME" branch. This makes it
possible to manage dotfiles from different users/hosts in a single
repository and checkout/merge specific parts without affecting the
configuration of other installations.

If existing the '~/.dotfilesrc' file can be used to customize certain
aspects (see CONFIGURATION below).

dotfiles is a very thin layer over 'git' it adds a few commands for
convenience but otherwise most git commands are available. Few git
commands are refined or disabled for safety reasons.

COMMANDS

  install
     install 'dotfiles' to ~/.dotfiles.sh and then to $2 or /usr/local/bin

  init
     initialize the '~/.dotfiles' repository

  help
     show this help

  autocommit
     do an automatic commit saving all pending changes (for cron)

  store
     add and commit files in one go (any non-file argument becomes the commit message)

  inventory
     list all files ever manged in dotfiles

  upgrade
     upgrade dotfiles itself

  force
     force a git command thats otherwise disabled or refined


CONFIGURATION

  The user can configure variables in '~/.dotfilesrc'. When this file
  does not exist or variables are not defined, defaults apply. This
  configuration should be done before calling 'dotfiles init'.

  DOTFILES_DIR="$HOME/.dotfiles"
    The directory where 'dotfiles' will create the local repository

  DOTFILES_BRANCH="$(whoami)@$(hostname)"
    Git branch name for local commits.

  DOTFILES_HOME="$HOME"
    The top-level directory to be tracked.

  DOTFILES_PUSH
    A list of remotes where to push automatically after storing changes.

  DOTFILES_UPGRADE
    remote/branch specification from where to update 'dotfiles' itself


EXAMPLES SETUP

  install from git (upstream) as /usr/local/bin/dotfiles
    git clone --sparse git://git.pipapo.org/dotfiles
    cd dotfiles
    bash dotfiles.sh install

  (re-)install as /usr/local/bin/dotfiles
    bash ~/.dotfiles.sh install

  initialize dotfiles once before use
    dotfiles init

  register a daily autocommit in the users crontab
    (crontab -l ; echo "@daily dotfiles autocommit" ) | crontab


  use 'git-crypt' for encrypting secret files

  initialize git-crypt
    dotfiles crypt init

  add your own gpg key for decryption
    dotfiles crypt add-gpg-user $(git config --get user.email)

  set up .gitattributes for files to be encrypted
    echo ".ssh/** filter=git-crypt diff=git-crypt" >>.gitattributes
    echo ".ssh/**/*.pub !filter !diff" >>.gitattributes
    echo ".gnupg/** filter=git-crypt diff=git-crypt" >>.gitattributes
    dotfiles store .gitattributes

  Confirm git-crypt is working
    dotfiles check-attr -a -- .ssh/*


EXAMPLES USAGE

  Add and commit changes in '.fileA' and 'FileB' with "commit
  message". Any non-file argument to 'store' is appended as to the
  commit message.
    dotfiles store .fileA FileB "commit message"

  list all files under dotfiles control
    dotfiles ls-files

  show git status/changes
    dotfiles status
    dotfiles diff

  Danger Zone (may destroy user data!)
    dotfiles force reset --hard


EXAMLES WORKFLOW

  Dotfiles allows one to keep the local history of configuration
  changes and undo them.

  Registering remotes allows to share these configurations, but for
  safety reasons pulling and merging is disabled in 'dotfiles' (git
  may inadvertly overwrite untracked but valuable files). Instead one
  would want to use checkout for single files and using that to merge
  on a per-file base, commit these when done.


EXAMPLE UPGRADE FROM UPSTREAM

  Updates dotfiles from the upstream/original repository
    dotfiles remote add upstream git://git.pipapo.org/dotfiles
    echo 'DOTFILES_UPGRADE="upstream/master"' >>.dotfilesrc
    dotfiles upgrade


HIDDEN FEATURES

  * 'dotfiles' can also manage regular files, despite it's name

  Untested:
  * It may work with git-annex and git-lfs and other git extensions


CONTRIBUTING

  This is an open project, fork it, hack it, send patches!
  Note that the 'README' is autogenerated by
    ./dotfiles.sh > README

  All content is in 'dotfiles.sh'.

  consider following as .git/hooks/pre-commit:
    #!/bin/sh
    bash dotfiles.sh > README
    git add README


LICENSE

    dotfiles -- manage your dotfiles in git
    Copyright (C) 2020  Christian Thäter <ct.dotfiles@pipapo.org>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.