NAME

dotf - dotfiles manager

VERSION

Version 0.001

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

• -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.

SUBCOMMANDS

dotf help

Prints the help page.

dotf init

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.

dotf status

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.

dotf update

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.

dotf version

Prints the version of dotf and exists.

EXIT STATUS

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

EXAMPLES

Example 1 Initializing dotf on a new system or account

$ 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.

Example 2 Update your dotfiles

$ dotf update

Example 3 Show uncommitted changes in your dotfiles

$ 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.

Example 4 Commit changed files

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.

Example 5 Add a new file to be managed by dotf

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

Example 6 Manage your own home directory for a shared account

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.

Create your own home directory

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

Install cpanm and local::lib

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

Prepare environment to install dotf

The following command must also be added to your profile.

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

Install dotf

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

Initialize dotf

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

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

Add sshss to modules.ini

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

Update dotfiles

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

Add entry to .ssh/authorized_keys in the shared accounts home directory

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"

Verify that you can login before closing your session

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

ENVIRONMENT

• 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.

RATIONALE

Why another dotfiles manager?

• 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.

SEE ALSO

modules.ini

SUPPORT

Bugs / Feature Requests

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.

Source Code

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

AUTHOR

Sven Kirmess [email protected]