yantonov / dot

Helps to use your configuration files (dotfiles) from the version control system.

Dot

Idea

Put configuration files (dot files) into the version control system.
To use saved files just create symbolic links to them.
This tool provides you with all the required automation by a single command.

Mechanics

Dot tool iterates over the current directory (including subdirectories) and creates symbolic links from ${HOME} to all files inside the current directory (source, target directories can be paramerized, HOME is the reasonable default).

Backup files will be generated before the creation of symbolic links (to preserve the existing content of the files that may be different than those you want to link).
Why you need backup: by default, on the fresh system, for example, it's possible that you already have some config files, the idea is to prevent missing any existing information.

No specific layout (directory structure) or additional configuration files are required, just run the program inside the directory which contains your dot files.

dot link

Installation

1. Put the binary (latest release) into the PATH
2. Use it from any directory (from your git repository or any other folder)

Windows specifics

You must have additional privileges to create symbolic links. You can set permissions here:

Configuration \ Windows Settings \ Security Settings \ Local Policies \ User Rights Assignment\ Create symbolic links

By default Administrator can create symbolic links. Make sure you run Git bash | Power shell | Cmd as administrator.

Examples

1. Bash files:
   common unix settings
   ubuntu settings
   mac settings
   Common files are located in a separate directory. Platform specifics - inside the corresponding folder.
2. nested directory example
   Run the dot tool inside the dotfiles directory.

Some tecnhical notes:

1. This implementation supports the simplest scenario to create symlinks, restore a regular file, and creating backup files before any symlink is introduced.
2. The composition of settings for different operation systems/platforms/devices can be done manually.
   Corresponding settings can be versioned in separate directories as you like and after that, you can call this tool manually from the selected directories.
3. There is no goal to reimplement inside this tool some functionality of the version control system (to add/remove tracked files, checking changes, etc), or ansible (to distribute files across multiple devices/instances).
4. You can try to use this tool for system files (/etc/something) using --target parameter if you have corresponding permissions to write to the target directory.
5. There is no intent to introduce extensive configuration settings,
   because in that case, it's easier to use a generic programming language and implement all required functionality using it.
   There is no profit to have just another indirection level for coping files, creating symbolic links, etc.

Inspired by:

1. missing-semester-course
2. dotfiler
3. dotfiles
4. homesick
5. dotfiles.github
6. atlassian.dotfiles bare git repo (nice, but it is hard to use dotfiles that are splitted into different repositories)
7. stow (nice, but
   a) I found it too late;
   b) there is no backup functionality;
   c) I wanted an interface that as simple as possible to cover the default case;
   d) stow has a little bit different ideology, for example about tree-folding.
   Why tree-folding (symlinks for the directory) is not implemented within this tool:
   the common and specific settings like overrides\extensions\customizations can be stored in different directories\repositories while they are using the same directory structure.
   In that case it's we have more than one target directory (with the base settings, with overrides\extensions) and that's why it's not possible to figure out what target directory should be used for the symbolic link.
8. lndir cannot handle relative directories, user experience is not so nice (not informative errors)
9. chezmoi too complicated for such trivial task, for multiple machines it's easier to have different folders (extract different parts and link it separately), than to have templates and code inside it (because it's hard to support files with multiple conditional statements inside it for different platforms).
10. dotbot too complicated + config is required

Thanks to all of these projects for the idea!

dot's Issues

Windows artifacts does not contain version number

Example: https://github.com/yantonov/dot/releases/tag/0.1.16

The goal is: investigate and fix release action

Return the corresponding exit code depending on the result of the operation

Rollback to existing file if it is impossible to create symbolic link

Scenario: you don't have enough privileges to create symbolic links (for example on windows).
Dot tries to create backup file then it removes the current file and tries to create symbolic link.
The creation will be failed and original file will be lost, so some functionality may be broken.
The goal is to restore the original file.

Multiple approaches can take place:

1. restore the original file explicitly;
2. check the required permissions in advance.

Support --source, --target

Idea: by default --source is equal to current dir, --target is equal to ${HOME} directory.
It would be nice to add parameterization for both directories.

Add check command to verify that all symbolic links exist