#+TITLE: dotfiles
Brice Waegeneire's dotfiles for *NIX, inspired by [[https://github.com/Kraymer/F-dotfiles][Kraymer/dotfiles]] and
[[https://github.com/terlar/dotfiles][terlar/dotfiles]].

** Tutorial
*** Dependencies
Those dotfiles depends on a minimal set of programs, most of which are
probably already installed on your system. If it's not the case install the
following packages with your package manager of choice:
- =git=, the version control system
- =stow=, a symlink manager
- =make=, as dependency manager
- =m4=, as theme engine

*** Using this dotfiles repository as a whole
To install all the configurations of this repository, enter the following in
 your terminal:
#+BEGIN_SRC sh
  git clone https://github.com/bricewge/dotfiles.git
  make all
#+END_SRC

*** Using part of the configurations
If you only want to use a /subset/ of the repository, let's say the
configuration just for =tmux= and =git=, then write the following in your
terminal:
#+BEGIN_SRC sh
  git clone https://github.com/bricewge/dotfiles.git
  make tmux git
#+END_SRC

** How-to guides
*** TODO How-to add a new module
*** TODO How-to add OS specific configuration
*** TODO How-to work on breaking changes
~git worktree~ but it doesn't work with ~git-crypt~
(AGWA/git-crypt#105) so maybe it can be replaced by
[[https://github.com/sobolevn/git-secret][git-secret]].

*** TODO How-to manage secrets
Some file contains sensitive information and are best being kept private to do
so we can encrypt them with ~git-crypt~.

However note that this method may not be sufficient in regard to your threat
model, in that case, please, do not put them on the Internet nor in a public
 ~git~ repository.

*** How to uninstall some modules
When you want to remove a specific module from your ~$HOME~ just do:
#+begin_src sh
  make uninstall PACKAGES=foo
#+end_src

To uninstall several modules at once, separate them with commas like this
~PACKAGES=foo,bar,baz~. If you want to remove all the modules then just do 
a ~make uninstall~.

*Note*: not all the installed modifications will be removed since it's only
an unstow of the symlinks. So what was done in stow's hooks ~pre-stow~ and
~post-stow~ /won't/ be removed.

*** TODO How-to use m4 as a theme engine
When a configuration format doesn't allow you to put a space before the variable
you want to be replaced with ~m4~ you need to quote the string before it.

Here is an example for ~polybar~ when using [[https://github.com/polybar/polybar/wiki/Formatting#format-tags][format tags]]:
#+begin_src txt
  separator = %{`F'COLOR_FOREGROUND_DIM}|%{F-}
#+end_src
Which, when passed through ~m4~ will result in:
#+begin_src txt
  separator = %{F#123456}|%{F-}
#+end_src

** Discussion
*** Priorities
**** Portable
Sticking strictly to POSIX's shell and requiring minimal dependencies make those
~dotfiles~ portable to most systems I use, in particular the ones running
~busybox~ that doesn't have ~bash~ installed and not much space to install
additional  software.

**** Modular
You will rarely need to install the configuration for all of the software you
have configure, except your workstation. You won't uses ~mpv~ configurations on
a server for example.

**** KISS
Declaring ~dotfiles~ bankruptcy never feel good, but not having a way to manage
all those configuration is worse. So let's keep it as simple as possible.

**** Hackable
They're will always be a time when you are forced to use a dirty workaround or
have some exotic edge-case to take into account, none of which a handy shell
script can't overcome.

*** TODO Why this organization?
*** TODO Past alternatives
Previous ways that I used to managed this repository.
**** unordered shell scripts
**** [[https://github.com/RichiH/vcsh][vcsh]] with [[https://github.com/RichiH/myrepos][myrepos]]
**** [[https://github.com/saltstack/salt][salt]]
**** [[https://github.com/mattly/bork][bork]]
- bash
- not maintained anymore
*** TODO Other alternatives

- =homemanager=, Nix based
** Reference
*** Module
*** Naming scheme
| Hierarchy pattern      | Description                                   | Example                       |
|------------------------+-----------------------------------------------+-------------------------------|
| _*                     | Will never be stowed                          | alacritty/_alacritty.terminfo |
| \@*                    | Subpackage, stowed when explicitly named      | gpg/@macos                    |
| {pre,post}-stow        | Executed before or after package installation | git/post-stow                 |
| .shell/login.d/*       | Evaluated by login shells                     | gpg/.shell/login.d/gpg        |
| .shell/interactive.d/* | Evaluated by interactive shells               |                               |

** License
All of this repository is under [[https://creativecommons.org/publicdomain/zero/1.0/][CC0 1.0]] license except the =wallpaper= subdirectory.