My Solution To Dotfile Management

• Use/Abuse
  • Emacs functions to add to init.el
  • How does it work?
  • Explanation of what is happening
  • How would I use this?
• External Tanglers
• TODO
• Reference for babel stuff

In the long long ago (2015), I used xstow and update-dotdee to construct my dotfiles from tiny pieces of files.

I have since evolved to this setup. Originally the intention was to make it easy for me to compile dotfiles based on certain parameters. Aka, my dotfiles are the same for x, y, and z, whatever those are, but for certain cases z should have one section be different or added etc… as the case may be.

Aka it was just a glorified program or templating system.

Since I already use org-mode to build my emacs configuration, why not just do the same for the dotfiles. Bonus, now I can have ALL my dotfiles in one logical file that can build itself.

So now if you want to look at my dotfiles, they're all in here. With one caveat that my emacs configuration is not. That is still separate. Mostly because it is large enough that it can stand on its own.

Use/Abuse

Use of this setup is somewhat simple or straightforward.

There really is one step in general:

  make

Emacs functions to add to init.el

For all this to work in emacs so you can edit source blocks you'll need add the following two functions otherwise you'll get an error every time you try to edit the source block.

  (defun tangle/yn (p) (if (bound-and-true-p p) "yes" "no"))
  (defun tangle/file (file p) (if (eval p) (concat "tmp/" file) "no"))

This is also all the "magique" that this whole stupid repo entails.

But how would you control how things get exported? Well that is done via files with simple (setq predicate-p t) lines inside them. These are all the options/name.el files comprise of.

But lets say you want to export things to another directory than $HE. No worries, just specify DEST:

  make DEST=/some/other/directory

But wait, what if you want to export things for an os you're not using?

Easy, just create a couple options files like so:

name=option
echo "(setq ${name}-p t)" > options/${name}.el
echo "(setq ${name}-p nil)" > options/no-${name}.el

And then provide the name (without the .el extension) to make via OPTS:

  make DEST=/some/other/directory OPTS=macos

This lets you customize things to a ludicrous degree at runtime like so:

  make OPTS=no-nix:linux:tmux:git:no-zsh

Etc…

I wouldn't do this exactly, while you could, thats just too much to need to remember to type. The simplest way to do things is to just create an options/$(ame -n).el file with all the options you need defined. Note that in the or BEGIN_SRC lines you can use elisp to control when/how something should or should not get tangled.

Example use of tangle/file, note the final option is just elisp and we just use bound-and-true-p to detect if we have a predicate or not.

  (tangle/file "some/file/name" (bound-and-true-p macos-p))
  (tangle/file "some/file/name" (bound-and-true-p foo-p))
  (tangle/file "some/file/name" (and (bound-and-true-p first-p) (bound-and-true-p second-p)))

By default the makefile will add an option with the name of the system its running on's uname -n. To override this behavior use the USEROPTS variable instead, or invoke things with a null HOST like so:

  make HOST=

Want to copy a specific generation to somewhere else? Or maybe you tested installing to some DEST, and want to copy that to $HE? No worries:

  make copy GEN=N

Where N is the generation you want to copy.

Note, to ensure this doesn't by default overwrite hand edited files, a diff is run across the files that would be copied to and what the tangled version contains.

Example, I've commented out some .gitignore lines in ~/.gitignore manually and then tried to tangle a new generation over the top.

./ddiff /Users/me/src/github.com/mitchty/dotfiles/generation/291 /Users/me
--- .gitignore  2017-03-04 12:49:17.000000000 -0600
+++ /Users/me/.gitignore 2017-03-04 14:00:24.000000000 -0600
@@ -8,6 +8,6 @@
 *.pyc
 *.rbc
 *.elc
-*.swp
-*.[oa]
-*.hi
+#*.swp
+#*.[oa]
+#*.hi
differences between /Users/me/src/github.com/mitchty/dotfiles/generation/291 and /Users/me

This is an attempt to ensure that we don't accidentally overwrite files that may have customizations on it.

To force it just run make copy GEN=N with N as the number to force a copy for.

How does it work?

It is really rather simple, the Makefile isn't that complex. Look at that for details.

This isn't intended to cover everything. This could be considered a template for how you could setup your files in a similar way. Look at this org mode file for details.

NOTE: Removal of files is YOUR job, not this tools. One could theoretically look at what changed between two generations and remove that way. BUT that sounds janky and error prone. Removal of files is the users job, not this setup.

Explanation of what is happening

This allows me to tangle files that would be useful for linux/bsd/etc… without affecting the existing files.

The general idea is this (look at Makefile for details):

• increment generation count from last generation

• tangle files to tmp/$fename based on current settings

• copy tmp to generation/N

• iff generation/(N-1) exists, diff each file there to what exists at DEST

• If diffing fails, the destination files have been updated, STOP, might lose hand edited changes. Note, if destination does not exist, this is ignored. Also setting FORCE will ignore this check.

• If diffing does not fail, hardlink generation/N/$fes to DEST/$fes

• Update last with current generation.

Note, the destination can be anywhere, not just $HE. This allows one to compile/tangle files that can then be trivially rsynced to remote machines, or to tar/xz the files as needed. The key here is emacs is only required to generate config files, not necessarily to use them.

How would I use this?

Should be easy enough to either clone this repo or copy things to a new repo and hack in what you need. Your call.

But, say you have a heading, take .profile as an example, under an org mode heading you would just add to your BEGIN_SRC definition like so:

  #+BEGIN_SRC sh :tangle .profile
  stuff

#+END_SRC

Then any source blocks for that heading will go to tmp/.profile. Its important that you put everything into tmp! This is used to generate things before a generation is built. It gives the Makefile a chance to know if the tangling worked or not.

But lets say you don't need to have lots of sub headings, or even control a file in multiple subparts that have predicates to control things.

Pretty simple, just add a source block like normal:

  #+BEGIN_SRC conf :tangle tmp/.example.conf
  put contents here!

#+END_SRC

External Tanglers

Putting everything in readme.org was getting annoying. So started to split things apart. Org links to all the

name	file
emacs	emacs.org
tmux	tmux.org
git	git.org
x	x.org
nix	nix.org
zsh	zsh.org
vim	vim.org
misc	misc.org
.profile	dotprofile.org
~/bin	bin.org

Language specific

name	file
haskell	haskell.org
perl	perl.org

TODO

• Figure out some way to make code blocks editable with :tangle, it sucks not being able to edit blocks as they are.

• Need to have some way to autocleanup old generations. Rm works for now so meh.

• Need to add the ability to detect that make is generating a pointless new generation. Aka generation N and generation N-1 are the same, just leave N and don't increment.

• Maybe checksum file contents somehow and use that?

• More? For now its functional.

Reference for babel stuff

Found this STUPID useful for constructing the tangle stuff.

babel scraps link