dotf - dotfiles manager

Version 0.001

• dotf [-h <homedir>] help
• dotf [-h <homedir>] init <url>
• dotf [-h <homedir>] status
• dotf [-h <homedir>] update
• dotf [-h <homedir>] version

The dotfiles manager dotf helps you synchronize your precious dotfiles between multiple Unix systems.

Your dotfiles will be maintained in one or multiple git repositories. These files are then linked with symlinks to your home directory.

If someone or something removes the symlink and replaces it with a copy of the file, the next run of dotf update will move the file back into the repository and recreate the symlink.

• -h homedir

  Specifies the directory that should be used as your home directory. This is the directory in which the dotfiles will be managed.

  If not specified, dotf defaults to your home directory as returned by File::HomeDir.

Prints the help page.

The init subcommand is used to initialize dotf on a new account. It takes a URL as argument which can be cloned with Git. This repository url will be cloned to ~/.files/.config and the master branch will be checked out.

dotf expects a file called modules.ini in the root of this repository.

The status subcommand can be used to show the changes in all Git repositories used by dotf. Use this command to see if there are some uncommitted changes.

The update subcommand is used to first update the .config repository. Then, the ~/.files/.config/modules.ini file is used to find all required Git repositories. These repositories will either be cloned or updated, as needed.

Repositories with uncommitted changes are skipped.

The update uses a --ff-only update.

Prints the version of dotf and exists.

The dotf utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line options were specified.

$ dotf init https://github.com/YOUR_ID/dotfiles-config-smartos.git

This clones the mentioned repositories to ~/.files/.config/, parses the modules.ini file in this repository and then clones all the repositories configured there.

You will probably use different config repositories for different operating systems or e.g. for home and work systems.

$ dotf update

$ dotf status

dotf replaces the managed dotfiles in your home directory with symlinks. The dotfiles are moved into the Git repositories under the ~/.file/ directory. The status subcommand can be used to get a git status -s of all your repositories.

The dotfiles are managed with Git. dotf does not interfere with this operation.

$ cd ~/.files/vim
$ git commit .vimrc
$ git push

It is important to push your changes after committing them to be able to use them on your other system/accounts.

This example shows how to start managing ~/.vimrc with dotf. You either need a new repository are use an existing one. To create a new one please see modules.ini.

$ cd ~/.files/vim/
$ mv ~/.vimrc ./
$ git add .vimrc
$ git commit -m 'initial commit of .vimrc' .vimrc
$ git push

The file is now in the vim Git repository. The last step is to create the ~/.vimrc symlink which will point to ~/.files/vim/.vimrc. This is done with:

$ dotf update

This example shows you how to bootstrap and manage your own home directory and use your preferred shell for a shared account with dotf and sshss.

We create a directory called .ryah under the home directory of the shared account. We will configure this as our own home directory and manage it with dotf.

$ cd ~
$ mkdir .ryah
$ cd .ryah
$ export HOME=$PWD

This will install them to the perl5 directory of your own home directory defined above.

$ unset PERL5LIB
$ unset PERL_MB_OPT
$ unset PERL_LOCAL_LIB_ROOT
$ unset PERL_MM_OPT
$ curl -L https://cpanmin.us | perl - App::cpanminus -l $HOME/perl5 local::lib

The following command must also be added to your profile.

$ eval "$(perl -I $HOME/perl5/lib/perl5 -Mlocal::lib)"

$ cpanm https://github.com/skirmess/App-Dotfiles.git

The -h option is not needed because $HOME was changed above.

$ dotf init https://github.com/YOUR_ID/dotfiles-config-smartos.git

The ~ points to the personal home because $HOME was changed above.

$ vi ~/.files/.config/modules.ini

Add sshss as module.

[sshss]
pull = https://github.com/skirmess/App-SSH-SwitchShell.git
source path prefix = bin
target path prefix = .ssh

Create the .ssh directory. We want dotf to only link the sshss script to the .ssh directory and not the whole directory.

$ mkdir ~/.ssh
$ dotf update

This must be added to the authorized_keys file of the shared account because sshss only changes your home directory and shell after the session is authenticated.

$ vi ~/../.ssh/authorized_keys

Add in front of your key:

command=".ryah/.ssh/sshss /usr/bin/ksh93"

Otherwise remove the command string again. Do not lock yourself out!

• HOME

  On UNIX used by File::HomeDir as primary method to identify your home directory.

  The home directory is where dotf places the .files directory which contains all the managed dotfiles.

• Implemented in Perl, Ksh or Bash

  I don't want to compile or install an obscure compiler or virtual machine on every system I'd like to use my dotfiles manager. Perl is most likely available on everything I'm interested in.

• Support for multiple configuration repositories

  I'd like to have my Vim configuration readily available on github, but the .profile file from my workplace should only be available on the Git server at my workplace.

• The configuration which dotfiles are installed on which system should also be under version control

  And changes to this configuration should automatically show up with an update. That's why we have the .config repository with the modules.ini file.

• I don't want the dotfiles manager to completely shield me from Git

  Git has a very powerful command line interface and you can find a huge amount of documentation on the Web. I don't want a dotfiles manager try to handle Git operations like merging, conflict resolution, etc. If there is a conflict to be resolved or a new file to be committed it should be done with Git directly. The dotfiles manager should only be a collection of convenient functions to make it easy to update changes on multiple system.

I was unable to find an existing dotfile manager that fulfilled these four requirements.

modules.ini

Please report any bugs or feature requests through the issue tracker at https://github.com/skirmess/App-Dotfiles/issues. You will be notified automatically of any progress on your issue.

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/skirmess/App-Dotfiles

git clone https://github.com/skirmess/App-Dotfiles.git

Sven Kirmess [email protected]