dotbare
is a command line utility to help manage dotfiles and or as a generic fuzzy git client. As a dotfile management tool,
it wraps around git bare repository, query git information from it and display them through fzf for an
interactive experience. It is originally inspired by forgit, a git wrapper using fzf.
dotbare
uses a different implementation approach and focuses on managing and interacting with system dotfiles. Because
of the flexible implementation of dotbare
, it can easily integrate with symlink/GNU stow setup or even as a generic
fuzzy git client to use in any git repository.
As a generic fuzzy git client (using --git
flag), dotbare
dynamically determine the top level .git
folder and process git information
and perform git operation in the current working tree.
You could find out how git bare repository could be used for managing dotfiles here.
Or a video explanation that helped me to get started. If you are currently
using a symlink/GNU stow setup, checkout how to integrate dotbare
with them here.
Select and edit dotfiles.
Stage and unstage dotfiles.
Interactive log viewer.
For more capabilities and commands, checkout wiki.
It has always been a struggle for me to get started with managing dotfiles using version control, as tools like "GNU stow" really scares me off with all the symlinks, until I found out about using git bare repository for managing dotfiles, zero symlinks, minimal setup required while keeping dotfiles at the location they should be.
However, it has always lack some interactive experience as it does not provide any auto completion on git commands nor file paths by default. It is also a pain when migrating the setup over to another system as you will have to manually resolve all the git checkout issues.
dotbare
solves the above problems by providing a series of scripts starts with a prefix f
(e.g. dotbare fadd
, dotbare flog
etc) that will enable a interactive experience by processing
all the git information and display it through fzf. In addition, dotbare
also comes with command line completion
that you could choose to either to complete git
commands or dotbare
commands.
dotbare
also comes with the ability to integrate with GNU stow or any symlink set up as long as you are using git.
It is easy to migrate to any system with minimal set up required. In addition, with a simple flag --git
, you can
now also use dotbare
as a generic fuzzy git client to manage any git repository.
dotbare
should work with any zsh plugin manager, below is only demonstration. Checkout wiki
about how to enable completion for zsh.
zinit light kazhala/dotbare
-
Clone the repository in to oh-my-zsh plugins directory.
git clone https://github.com/kazhala/dotbare.git $HOME/.oh-my-zsh/custom/plugins/dotbare
-
Activate the plugin in
~/.zshrc
.plugins=( [plugins...] dotbare [plugins...] )
antigen bundle kazhala/dotbare
-
Clone the repository (change ~/.dotbare to the location of your preference).
git clone https://github.com/kazhala/dotbare.git ~/.dotbare
-
Put below into
.zshrc
.source ~/.dotbare/dotbare.plugin.zsh
dotbare
comes with a dotbare.plugin.bash
which contains the command line completion
function for both git
and dotbare
, checkout wiki
about how to enable it.
-
Clone the repository (change ~/.dotbare to the location of your preference).
git clone https://github.com/kazhala/dotbare.git ~/.dotbare
-
Put below into
.bashrc
or.bash_profile
.source ~/.dotbare/dotbare.plugin.bash
-
Clone the repository (change ~/.dotbare to the location of your preference).
git clone https://github.com/kazhala/dotbare.git ~/.dotbare
-
Add
dotbare
to your PATH.# This is only an example command for posix shell # If you are on fish, use the fish way to add dotbare to your path export PATH=$PATH:$HOME/.dotbare
Or you could create a alias which point to dotbare executable.
alias dotbare="$HOME/.dotbare/dotbare"
You will need git on the system for obvious reasons..and because dotbare
is written in bash,
it will require you to have bash in the system (You don't need to run bash, just need to be in the system).
-
tree (Provide a directory tree view when finding directory)
# if you are on macos brew install tree
-
bat or highlight or coderay or rougify (Syntax highlighting when previewing files, otherwise cat will be used)
-
delta or diff-so-fancy or any diff tools of your choice (Fancy git diff preview like in the screen shot)
-
init git bare repository.
Note: by default,
dotbare finit
will set up a bare repository in $HOME/.cfg, to customize location and various other settings, checkout customizationdotbare finit
-
add dotfiles you want to track.
Treat
dotbare
as normalgit
commands.dotbare fadd -f # or dotbare add [FIELNAME] # add entire repository like .config directory dotbare fadd -d # or dotbare add [DIRECTORY]
-
commit changes and push to remote.
dotbare commit -m "First commit" dotbare remote add origin [URL] dotbare push -u origin master
-
follow the steps in install to install
dotbare
. -
check your current alias of git bare reference.
# Below is an example alias, check yours for reference alias config=/usr/bin/git --git-dir=$HOME/.cfg --work-tree=$HOME
-
set env variable for
dotbare
.export DOTBARE_DIR="$HOME/.cfg" export DOTBARE_TREE="$HOME"
-
remove the original alias and use
dotbare
. -
optionally you could alias
config
todotbare
so you keep your muscle memory.alias config=dotbare
-
follow the steps in install to install
dotbare
. -
set environment variable so that
dotbare
knows where to look for git information.# e.g. I have all my dotfiles stored in folder $HOME/.myworld and symlinks all of them to appropriate location. # export DOTBARE_DIR="$HOME/.myworld/.git" # export DOTBARE_TREE="$HOME/.myworld" export DOTBARE_DIR=<Path to your .git location> export DOTBARE_TREE=<Path to directory which contains all your dotfiles>
-
Run
dotbare
anywhere in your system.
Note: with this method, you do not run dotbare finit -u [URL]
when migrating to new system,
you will do your normal migration steps and then do the above steps.
While bare method is great and easy, I recommend keeping your current symlink/GNU stow setup and integrate it with dotbare
instead of a migration.
If you are really happy with dotbare
, as long as your remote repository resembles the structure of your home holder
(reference what I mean in my repo), simply run the command below.
Disclaimer: I have not done nearly enough test on this as I don't personally use symlink/GNU stow setup, migrate this way with caution. I recommend you test this migration in docker, see Test-it-in-docker.
# dotbare will replace all symlinks with the original file and a bare repository will be created at $DOTBARE_DIR
dotbare finit -u [URL]
-
follow the steps in install to install
dotbare
. -
Optionally set env variable to customize
dotbare
location (checkout customization).export DOTBARE_DIR="$HOME/.cfg" export DOTBARE_TREE="$HOME"
-
give
dotbare
your remote URL and let it handle the rest.dotbare finit -u https://github.com/kazhala/dotfiles.git
When you are about to do migrations, I strongly suggest you give the migration a try in docker first.
The dotbare
image is based on alpine linux.
docker pull kazhala/dotbare:latest
docker container run -it --rm --name dotbare kazhala/dotbare:latest
dotbare
could be customized through modification of env variables.
Note: customization of fzf is not covered here, checkout their wiki.
This is the location of the bare repository, dotbare
will look for this directory
and query git information or it will create this directory when initializing dotbare
.
Change this to location or rename the directory to your liking.
If you are using symlink/GNU stow setup, set this variable point to the .git folder within your dotfile directory.
# Default value
export DOTBARE_DIR="$HOME/.cfg"
This is the working tree for the git bare repository, meaning this is where the version control will take place. I don't recommend changing this one unless ALL of your config file is in something like $XDG_CONFIG_HOME. If you are using symlink/GNU stow setup, set this variable to point to the folder containing all of your dotfiles.
# Default value
export DOTBARE_TREE="$HOME"
This variable is used to determine where to store the backup of your files. It is used
mainly by dotbare fbackup
which will back up all of your tracked dotfiles into this location.
It is also used by dotbare finit -u [URL]
, when there is checkout conflict, dotbare
will
automatically backup conflicted files to this location.
# Default value
export DOTBARE_BACKUP="${XDG_DATA_HOME:-$HOME/.local/share}/dotbare"
This is probably already set in your ENV. dotbare
uses this variable to determine
which editor to use when running dotbare fedit
.
# Default value
export EDITOR="vim"
This variable set default keybinds for fzf in dotbare
. You could checkout a list of keybinds
to set here.
# Default value
export DOTBARE_KEY="
--bind=alt-a:toggle-all # toggle all selection
--bind=alt-j:jump # label jump mode, sort of like vim-easymotion
--bind=alt-0:top # set cursor back to top
--bind=alt-s:toggle-sort # toggle sorting
--bind=alt-t:toggle-preview # toggle preview
"
Customize fzf settings for dotbare. This is useful when you want a different fzf behavior from your normal system fzf settings.
# By default this variable is not set
# More settings checkout fzf man page and their wiki
# Example: if you want your preview window for dotbare to be bigger
export DOTBARE_FZF_DEFAULT_OPTS="--preview-window=right:65%"
This variable determines the preview command for file previews. By default, the preview is automatically determined using fall back (bat -> highlight -> coderay -> rougify -> cat). Set this variable to control the preview command if you have a specific preference or if you want extra flags/settings. Reference here.
# By default this value is not set, dotbare uses a fall back method to determine which command to use.
# Make sure to have "{}" included when customizing it, the preview script substitute "{}" for actual filename.
# Example: enable line number for cat command
export DOTBARE_PREVIEW="cat -n {}"
This variable controls the diff output pager in previews like dotbare flog
, dotbare fadd
etc. It will read the value
of git config core.pager
to determine the pager to use. If you have a specific preference for dotbare
or have not set
the global pager in git config, you could use this variable to customize the diff preview.
# By default this value uses fall back (git config core.pager -> cat)
export DOTBARE_DIFF_PAGER="delta --diff-so-fancy --line-numbers"
All usage and commands are documented in wiki.
Latest changes are documented in CHANGELOG.
dotbare
is unit tested using bats. Mock tests are implemented using PATH override method.
This is documented here for better readability and extensibility.
Not all functions have 100% coverage and lots of user interaction cannot be effectively tested, please fire up issues if something went wrong.
I've added AWSCodeBuild to CI/CD to build the docker image. It is mainly for my personal practice. If you are interested in what's happening in AWSCodeBuild you could checkout my cloudformation template.
Checkout out CONTRIBUTING.md to see how you could contribute to dotbare
. PRs are
welcome and I'm happy to improve/extend dotbare
's functionality.
Don't forget to leave a star :)
dotbare
was initially part of my personal scripts, I had a hard time sharing those scripts
and as the number of scripts grows, I feel like is more appropriate to make a dedicated project
for it. I hope you find it useful and enjoy it, thanks!
- credit to forgit for inspiration.
- credit to fzf for fzf and the preview script from fzf.vim.
- credit to OMZ for upgrading method.
- credit to this post for step by step guide of setting up git bare repo.
- credit to this video for introducing git bare repo.
You could find some more demo here