briefcase is a tool to facilitate keeping dotfiles in git, including those with private information (such as
By keeping your configuration files in a git public git repository, you can share your settings with others. Any secret information is kept in a single file outside the repository (it’s up to you to backup and transport this file).
$ gem install briefcase $ briefcase import ~/.bashrc You don't appear to have a git repository at /Users/jim/.dotfiles. Do you want to create one now? ? (create or abort) c Creating git repository at /Users/jim/.dotfiles
At this point, a git repository will have been created at
bashrc will have been moved there and added to the git index. You can verify this using
briefcase git, which passes everything through to the
git executable (assuming it is installed and on your path).
$ briefcase git status # On branch master # Changes to be committed: # (use "git rm --cached <file>..." to unstage) # # new file: bashrc
You’ll probably want to check the
bashrc file into your new git repo. Which can be done using the
git command again.
$ briefcase git ci -m "Added bashrc"
Great. You’ve successfully added the first file to your new dotfiles repo. I recommend creating a repo on Github or another Git hosting service, adding it as a remote, and pushing your dotfiles there for safekeeping.
$ briefcase git remote add origin firstname.lastname@example.org:jim/dotfiles.git $ briefcase git push origin master
Imports a dotfile into the dotfiles directory, moving it to the dotfiles directory and replacing it with a symlink to its new location.
$ briefcase import ~/.vimrc Importing /Users/jim/.vimrc into /Users/jim/.dotfiles Moving /Users/jim/.vimrc to /Users/jim/.dotfiles/vimrc Symlinking /Users/jim/.vimrc -> /Users/jim/.dotfiles/vimrc Done.
Imports a dotfile that contains sensitive information.
$ briefcase redact ~/.config_with_secrets Importing /Users/jim/.config_with_secrets into /Users/jim/.dotfiles Moving /Users/jim/.config_with_secrets to /Users/jim/.dotfiles/config_with_secrets Symlinking /Users/jim/.config_with_secrets -> /Users/jim/.dotfiles/config_with_secrets Creating redacted version at /Users/jim/.dotfiles/config_with_secrets.redacted
The user is presented with an editor (either
vim or the value of the environment variable
BRIEFCASE_EDITOR), where sensitive information like this:
can be replaced with what appears to be a commented out call to a briefcase function:
password: # briefcase(password)
When the file is saved and closed, Briefcase will detect this change and save
superSecretPassword to the sercets file using the key
The edited file is then saved with a
.redacted extension, and the original file is added to
~/.dotfiles/.gitignore so it will not be added to the repository.
Storing secret value for key: password Adding /Users/jim/.dotfiles/config_with_secrets.redacted to /Users/jim/.dotfiles/.gitignore Done.
Creates a symlink in the user’s home directory for each dotfile in the dotfiles directory.
$ briefcase sync Synchronizing dotfiles between /Users/jimb/.dotfiles and /Users/jimb Symlink verified: /Users/jimb/.ackrc -> /Users/jimb/.dotfiles/ackrc Symlink verified: /Users/jimb/.autotest -> /Users/jimb/.dotfiles/autotest Symlink verified: /Users/jimb/.gitconfig -> /Users/jimb/.dotfiles/gitconfig Symlink verified: /Users/jimb/.gvimrc -> /Users/jimb/.dotfiles/gvimrc Symlink verified: /Users/jimb/.irbrc -> /Users/jimb/.dotfiles/irbrc Symlink verified: /Users/jimb/.vim -> /Users/jimb/.dotfiles/vim Symlink verified: /Users/jimb/.vimrc -> /Users/jimb/.dotfiles/vimrc Symlink verified: /Users/jimb/.zshenv -> /Users/jimb/.dotfiles/zshenv Symlink verified: /Users/jimb/.zshrc -> /Users/jimb/.dotfiles/zshrc Done.
Creates local versions of all redacted dotfiles, using information found in the secrets file to fill in any values that were removed.
$ briefcase generate Generating redacted dotfiles in /Users/jim/.dotfiles Generating /Users/jim/.dotfiles/gitconfig Loading existing secrets from /Users/jim/.briefcase_secrets Restoring secret value for key: git_user Restoring secret value for key: git_email Restoring secret value for key: github_user Restoring secret value for key: github_token Done.
git command passes all commands through to the
git executable, assuming it is installed on your path. All commands are executed in your dotfiles directory.
$ briefcase git status # On branch master nothing to commit (working directory clean)
With briefcase, dotfiles are stored in a centralized location (by default ~/.dotfiles), and symlinks are created for these files in the user’s home directory. Here is a basic setup for a .gitconfig file:
+-~/ Home directory | +-.briefcase_secrets Secrets file | +-.gitconfig Symlink to ~/.dotfiles/gitconfig | +-.dotfiles/ Dotfiles directory | | +-gitconfig Standard Dotfile | | +-gitconfig.redacted Redacted dotfile
Where the action happens. Dotfiles that normally exist here are replaced by symlinks to files in the dotfiles directory.
~Override by setting BRIEFCASE_HOME_PATH in your environment.
Where dotfiles are stored.
~/.dotfilesOverride by setting BRIEFCASE_DOTFILES_PATH in your environment.
There are two types of dotfiles.
A basic config file that would normally live in a user’s home directory.
A config file that contains some secret information. The file is stored, sans secret info, with a ‘.redacted’ extension in the repo. The dotfile that is symlinked to the user’s home directory is then generated from this file.
This file contains the information removed from dotfiles imported using the redact command.
~/.briefcase_secretsOverride by setting BRIEFCASE_SECRETS_PATH in your environment.
Copyright (c) 2012 Jim Benton. See LICENSE for details.