dotbare

Introduction

dotbare is a command line utility to help you manage your dotfiles. It wraps around git bare repository and heavily utilise fzf for better user experience. It is inspired by forgit, a git wrapper that utilise fzf for interactive experience. dotbare uses a different implementation approach and focuses on managing and interacting with your dotfiles. Don't worry about migration if you have a symlink/GNU stow setup, you can easily integrate dotbare with them.

Pros:

• No symlink
• Simple setup/remove
• Customizable
• Easy migration
• Flat learning curve
• Manage dotfiles in any directory
• Integration with symlink/GNU stow setup

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 currently is using symlink/GNU stow setup, checkout how to integrate dotbare with them here.

Why

It has always been a struggle for me to get started with managing dotfiles using version control, as some other 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 and you keep your 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. 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.

Table of Contents

• Install
  • zsh
  • bash
  • others
• Getting started
  • Dependencies
  • Setup
  • Migration
    • Migrating from normal git bare repository
    • Migrating from a generic symlink setup or GNU stow
    • Migrating dotbare to a new system
    • Test it in docker
• Customization
  • DOTBARE_DIR: location of the git directory
  • DOTBARE_TREE: location of the working index
  • DOTBARE_BACKUP: location to backup files
  • EDITOR: editor used to open files
  • DOTBARE_KEY: keybinds
  • DOTBARE_FZF_DEFAULT_OPTS: fzf customization
• Commands
  • Checkout all available scripts and their help manual
  • fedit: edit dotfiles
  • fadd: stage changes
  • freset: unstage changes
  • fcheckout: discard changes/checkout commits and branch
  • flog: interactive log viewer
  • fstash: stash management
  • fbackup: backup tracked files
  • fstat: toggle stage/unstage files
  • finit: initialise/migrating dotbare
  • funtrack: untrack files
  • fupgrade: update dotbare
• Tips and Tricks
• Testing
• Contributing
• Coming up
• Background
• Credit
• Demo

Install

zsh

dotbare should work with any zsh plugin manager, below is only demonstration

zinit

zinit light kazhala/dotbare

oh-my-zsh

• 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

antigen bundle kazhala/dotbare

Manual

• 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
  

bash

dotbare comes with a dotbare.plugin.bash which will enable both bash command line completion for dotbare commands and adding dotbare to your PATH. If you don't want the completion, simply follow the instructions in others and add dotbare to your PATH.

• 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
  

others

1. Clone the repository (change ~/.dotbare to the location of your preference)

   git clone https://github.com/kazhala/dotbare.git ~/.dotbare
   

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

3. Or you could create a alias which point to dotbare executable

   alias dotbare="$HOME/.dotbare/dotbare"
   

Getting started

Dependencies

• Required dependency

  • fzf
  • bash(You don't need to run bash, but dotbare does require you have bash in your system)

• Optional dependency

  • tree (Will provide a directory tree view when finding directory)

    # if you are on macos
    brew install tree
    

Setup

1. init git bare repository

   Note: by default, dotbare finit will set up a bare repo in $HOME/.cfg, to customize location and various other settings, checkout customization

   dotbare finit
   

2. add dotfiles you want to track

   # Treat dotbare as normal `git` commands.
   
   dotbare fadd -f
   # or
   dotbare add [FIELNAME]
   
   # add entire repository like .config
   dotbare fadd -d
   # or
   dotbare add [DIRECTORY]
   

3. commit changes and push to remote

   dotbare commit -m "First commit"
   dotbare remote add origin [URL]
   dotbare push -u origin master
   

Migration

Migrating from normal git bare repository

1. follow the steps in install to install dotbare

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

3. set env variable for dotbare

   export DOTBARE_DIR="$HOME/.cfg"
   export DOTBARE_TREE="$HOME"
   

4. remove the original alias and use dotbare the same except with super power

5. optionally you could alias config to dotbare so you keep your muscle memory

   alias config=dotbare
   

Migrating from a generic symlink setup or GNU stow

If you already have a symlink setup either custom or with GNU stow. You could either integrate dotbare with your current set up or do a complete migration.

Keep your current setup but integrate dotbare

1. follow the steps in install to install dotbare

2. 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 directory>
   export DOTBARE_TREE=<Path to directory which contains all your dotfiles>
   

3. Run dotbare anywhere in your system

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

Complete migration

I haven't used GNU stow or any symlink setup, but I do recommend keep your current setup and integrate with dotbare. 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 test this with GNU stow, migrate in this way with caution.
# I recommend you test this migration in docker, see #Test-it-in-docker
dotbare finit -u [URL]

Migrating dotbare to a new system

1. follow the steps in install to install dotbare

2. Optionally set env variable to customize dotbare location. Checkout customization

   export DOTBARE_DIR="$HOME/.cfg"
   export DOTBARE_TREE="$HOME"
   

3. give dotbare your remote URL and let it handle the rest

   dotbare finit -u https://github.com/kazhala/dotfiles.git
   

Test it in docker

I strongly suggest you give dotbare a try in docker, especially when it comes to first time migration.

docker pull kazhala/dotbare:latest
docker container run -it --rm --name dotbare kazhala/dotbare:latest

Customization

dotbare could be customized through modification of env variables.

Note: customization of fzf is not covered here, you should checkout their wiki.

DOTBARE_DIR

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 your .git folder in your working directory of your dotfiles.

# Default
DOTBARE_DIR="$HOME/.cfg"

DOTBARE_TREE

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 or if you are using symlink/GNU stow setup, set this variable to point to the folder contains your actual dotfiles.

# Default
DOTBARE_TREE="$HOME"

DOTBARE_BACKUP

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. You probably shouldn't change this location.

# Default
# 2. If XDG_DATA_HOME exist, use XDG_DATA_HOME/dotbare
# 3. otherwise, use $HOME/.local/share/dotbare
DOTBARE_BACKUP="${XDG_DATA_HOME:-$HOME/.local/share}/dotbare"

EDITOR

This is probably already set in your ENV. dotbare uses this variable to determine which editor to use when running dotbare fedit.

# Default
EDITOR="vim"

DOTBARE_KEY

This variable set default keybinds for fzf in dotbare. You could checkout a list of keybinds to set here.

# Default
DOTBARE_KEY="
  --bind=alt-a:toggle-all       # toggle all selection
  --bind=alt-j:jump             # label jump mode, sort of like easymotion
  --bind=alt-0:top              # set cursor back to top
  --bind=alt-s:toggle-sort      # toggle sorting
  --bind=alt-t:toggle-preview   # toggle preview
"

DOTBARE_FZF_DEFAULT_OPTS

Customize fzf settings for dotbare. This is useful when you want a different fzf behavior from your normal system fzf settings.

# Default is unset
# More settings checkout fzf man page and their wiki
# You could also take a look at my fzf config
# https://github.com/kazhala/dotfiles/blob/5507a2dea4f4a420e6d65a423abaa247521f89a8/.zshrc#L56

Commands

dotbare doesn't have a man page yet, will come later, for help, type dotbare [COMMAND] -h

Checkout all available scripts and their help manual

# run dotbare without any arguments
dotbare
# or checkout help for dotbare
dotbare -h
dotbare help
# for normal git help
dotbare --help

fedit

List all tracked dotfiles and edit the selected file through $EDITOR, it also support edit commits through interactive rebase.

• Default: list all tracked files and open $EDITOR to edit it. Support multi selection.
• -m: list all modified files and open $EDITOR to edit it. Support multi selection.
• -c: list all commits and open interactive rebase to edit commits.

fadd

Stage modified files, stage new file or directory interactive by through fzf.

• Default: list all modified files and stage selected files. Support multi selection.
• -f, --file: list all files in current directory and stage selected files. Support multi selection. (Used for staging new files to index)
• -d, --dir: list all directory under current directory and stage selected directory. Support multi selection. (Used for staging new files to index)

freset

Reset/unstage file, reset HEAD back to certain commits and reset certain file back to certain commits. Also supports reset HEAD back to certain commits either --soft, --hard, --mixed, as well as reset a file back to certain commits. More information on differences here.

• Default: list all staged files and unstage the selected files. Support multi selection.
• -c, --commit: list all commits and then reset HEAD back to the selected commits. (Default: --mixed, put all changes into modified state)
• -S, --soft: use --soft flag instead of --mixed flag, reset HEAD to certain commit without modify working tree.
• -H, --hard: use --hard flag instead of --mixed flag, reset HEAD to certain commit discard all changes from the working tree.

fcheckout

Checkout files/commit/branch interactively.

• Default: list all modified files and reset selected files back to HEAD. Support multi selection. (Discard all changes) Note: if your file is staged, you will need to unstage first before running fcheckout to make it work.
• -a: list all tracked files and then prompt commit selection, checkout selected file in the version of selected commit.
• -b: list all branch and switch to selected branch.
• -c: list all commits and checkout selected commit.

flog

Interactive log viewer that will prompt you with a menu after selecting a commit. Allows edit, reset, revert and checkout the selected commits.

• Default: list all commits and then prompt menu to select actions.
• -r: revert the selected commit
• -R: reset HEAD back to the selected commit
• -e: edit selected commit through interactive rebase
• -c: checkout selected commit

fstash

View and manage stash interactively.

• Default: list all stash and apply the selected stash. (Default: apply)
• -f: list modified files and only stash selected files. Support multi selection.
• -d: list all stash and delete selected stash. Support multi selection.
• -p: use pop instead of apply. (pop would remove the stash while apply preserve the stash)

fbackup

Backup all of the tracked dotfiles to $DOTBARE_BACKUP directory. This is used also by dotbare finit -u [URL] for backing up conflicted checkout files.

• Default: backup all tracked dotfiles to $DOTBARE_BACKUP directory. (Default: use cp)
• -s: list all tracked files and only backup selected files. Support multi selection.
• -p PATH: specify path to files and then backup. (This is mainly used by dotbare finit -u [URL])
• -m: use mv instead of cp to backup. (This is mainly used by dotbare finit -u [URL])

fstat

Interactively toggle stage/unstage of files. This is less used compare to dotbare fadd, it might get deprecated.

finit

Initialise dotbare with a bare repository or add -u [URL] flag for migrating current dotfiles to a new system.

Note: do not use this command if you are using symlink/GNU stow.

• Default: initialise a git bare repository at $DOTBARE_DIR
• -u URL: migrate existing bare repository from remote to current system.
• -s: if you have defined submodules in your bare repo (i.e. containes .gitmodule), add -s flag to clone submodules as well during migration.

funtrack

Stop tracking the selected git files. It could also be used to temporarily stop tracking changes for files and then later on resume tracking changes.

Note: This command has severe limitations.

By default, selected files are permanently untracked starting from next commit. It will not remove it from history. And if your other system pull down the new commit, the untracked files on the other system will actually get removed by git. This is a limitation with git, to overcome this, after untracking the files, run dotbare fbackup to backup the files. After pulling new changes, move the deleted files from backup back to their original position. More discussions here.

dotbare funtrack does come with capabilities to temporarily untrack files, which will not actually remove the untracked files from other system. However, this is NOT recommended way to untrack files, explained here.

• Default: list all tracked files and permanently untrack the selected files. Support multi selection.
• -s: list all tracked files and temporarily untrack changes of the selected files. Support multi selection.
• -S: list all tracked files and resume tracking changes of the selected files.

fupgrade

Update dotbare to the latest version in master. It basically just pull down changes from master, except you don't have to cd into dotbare directory, you can run this command any where.

Tips and Tricks

• Most commands related to files support multi selection (default fzf setting is TAB)

• Most commands related to commits and branches doesn't support multi selection

• Checkout fzf doc for more default fzf keybinds information.

• Alias dotbare to shorter words to type less

  alias db=dotbare
  

• Create keybinds for dotbare (e.g. bind ctrl-g to launch fedit and edit files)

  # zsh example
  bindkey -s '^g' "dotbare fedit"^j
  # bash example
  bind -x '"\C-g":"dotbare fedit"'
  

• dotbare has disabled the command dotbare add --All as it is a really dangerous command in the conext of dotbare as it will stage everything in your $DOTBARE_TREE to the index.

  # Recommended ways
  dotbare fadd  # and then press alt-a to select all
  dotbare add -u # stage all modified file to index
  dotbare commit -am "message" # this also works, it will stage all modified files and then commit
  

• Add the value of $DOTBARE_DIR to global .gitignore to avoid any weird recursion problem if accidentally adding $DOTBARE_DIR to index, the value needs to be relative path to $DOTBARE_TREE

  # e.g. DOTBARE_DIR="$HOME/.cfg", DOTBARE_TREE="$HOME"
  echo ".cfg" >> $HOME/.gitignore
  # e.g. DOTBARE_DIR="$HOME/.config/.cfg" DOTBARE_TREE="$HOME"
  echo ".config/.cfg" >> $HOME/.gitignore
  # e.g. DOTBARE_DIR="$HOME/.config/.cfg" DOTBARE_TREE="$HOME/.config"
  echo ".cfg" >> $HOME/.gitignore
  

Testing

dotbare is unit tested on a best effort due the nature of fzf which require human input. Mock test are coming if I could make it work.

Some functions may have a lot more coverage than others, so please fire up issues if something went wrong. dotbare uses bats to test individual functions.

I've added AWSCodeBuild to CI/CD just for my personal practice, if you are interested in what's happening in AWSCodeBuild you could checkout my cloudformation template.

Contributing

Please help me out by pointing out things that I could improve, I've only been scripting for a few months and are still adapting many new things every day. PR are always welcome and please fire up issues if something went wrong.

Leave a star if possible :)

Coming up

• Improve unit test with mocking
• Support submodules during migration
• Command line completion for dotbare in zsh
• Command line completion for dotbare in bash
• Man page
• Installation method

Background

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

• credit to forgit for inspiration.
• credit to fzf for fzf.
• credit to this post for step by step guide of setting up git bare repo.
• credit to this video for introducing git bare repo.

Demo

You could find some more gif demo here