{"id":13587996,"url":"https://github.com/kazhala/dotbare","last_synced_at":"2025-04-04T08:06:59.889Z","repository":{"id":37183865,"uuid":"253399036","full_name":"kazhala/dotbare","owner":"kazhala","description":"Manage dotfiles and any git directories interactively with fzf","archived":false,"fork":false,"pushed_at":"2024-04-28T02:15:31.000Z","size":308,"stargazers_count":693,"open_issues_count":11,"forks_count":20,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-28T07:05:23.932Z","etag":null,"topics":["bash","bash-script","command-line-tool","config","dotfiles","dotfiles-manager","fzf","fzf-scripts","zsh","zsh-plugin"],"latest_commit_sha":null,"homepage":"https://github.com/kazhala/dotbare/wiki","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kazhala.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-06T04:59:39.000Z","updated_at":"2025-03-26T21:32:00.000Z","dependencies_parsed_at":"2024-06-21T16:51:08.447Z","dependency_job_id":"30df8fcc-9f71-4123-889f-53a9d4de82e5","html_url":"https://github.com/kazhala/dotbare","commit_stats":{"total_commits":392,"total_committers":5,"mean_commits":78.4,"dds":"0.015306122448979553","last_synced_commit":"791d8e08c7b121f7ecb3f2f1a1d763c682048740"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazhala%2Fdotbare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazhala%2Fdotbare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazhala%2Fdotbare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kazhala%2Fdotbare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kazhala","download_url":"https://codeload.github.com/kazhala/dotbare/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142042,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-script","command-line-tool","config","dotfiles","dotfiles-manager","fzf","fzf-scripts","zsh","zsh-plugin"],"created_at":"2024-08-01T15:06:27.580Z","updated_at":"2025-04-04T08:06:59.859Z","avatar_url":"https://github.com/kazhala.png","language":"Shell","readme":"# dotbare\n\n![CI Status](https://github.com/kazhala/dotbare/workflows/CI/badge.svg)\n![AWSCodeBuild](https://codebuild.ap-southeast-2.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiVVo4eUt6T0JGSFU1M1plVml0Y1dOWkJnaTV0eWZNNm5uY043Z3MwaUY2aUhaTHllQklhaVFiWmxIcTNVc0ZFRFhwbFdpZ3dsb3RMZFU0aDk3S1FUQUpRPSIsIml2UGFyYW1ldGVyU3BlYyI6ImVUdjloSlNTa3NyTUJVemIiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D\u0026branch=master)\n![Platform](https://img.shields.io/badge/platform-macos%20%7C%20linux-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n## Introduction\n\n`dotbare` is a command line utility to help manage dotfiles and or as a generic fuzzy git client. As a dotfile management tool,\nit wraps around git bare repository, query git information from it and display them through [fzf](https://github.com/junegunn/fzf) for an\ninteractive experience. It is originally inspired by [forgit](https://github.com/wfxr/forgit), a git wrapper using fzf.\n`dotbare` uses a different implementation approach and focuses on managing and interacting with system dotfiles. Because\nof the flexible implementation of `dotbare`, it can easily integrate with symlink/GNU stow setup or even as a generic\nfuzzy git client to use in any git repository.\n\nAs a generic fuzzy git client (using `--git` flag), `dotbare` dynamically determine the top level `.git` folder and process git information\nand perform git operation in the current working tree.\n\nYou could find out how git bare repository could be used for managing dotfiles [here](https://www.atlassian.com/git/tutorials/dotfiles).\nOr a [video](https://www.youtube.com/watch?v=tBoLDpTWVOM\u0026t=288s) explanation that helped me to get started. If you are currently\nusing a symlink/GNU stow setup, checkout how to integrate `dotbare` with them [here](#migrating-from-a-generic-symlink-setup-or-gnu-stow).\n\nSelect and edit dotfiles.\n![fedit](https://user-images.githubusercontent.com/43941510/87669391-37f28180-c7b1-11ea-907d-3b26f363a279.png)\nStage and unstage dotfiles.\n![fstat](https://user-images.githubusercontent.com/43941510/87669408-43de4380-c7b1-11ea-8a31-fc702eb69804.png)\nInteractive log viewer.\n![flog](https://user-images.githubusercontent.com/43941510/87669399-3e80f900-c7b1-11ea-9bfa-5db31c4307c3.png)\nFor more capabilities and commands, checkout [wiki](https://github.com/kazhala/dotbare/wiki/Commands).\n\n## Why\n\nIt has always been a struggle for me to get started with managing dotfiles using version control,\nas tools like \"GNU stow\" really scares me off with all the symlinks, until I found\nout about using git bare repository for managing dotfiles, zero symlinks, minimal setup\nrequired while keeping dotfiles at the location they should be.\n\nHowever, it has always lack some interactive experience as it does not provide any auto\ncompletion on git commands nor file paths by default. It is also a pain when migrating the setup over\nto another system as you will have to manually resolve all the git checkout issues.\n\n`dotbare` solves the above problems by providing a series of scripts starts with a prefix f\n(e.g. `dotbare fadd`, `dotbare flog` etc) that will enable a interactive experience by processing\nall the git information and display it through fzf. In addition, `dotbare` also comes with command line completion\nthat you could choose to either to complete `git` commands or `dotbare` commands.\n`dotbare` also comes with the ability to integrate with GNU stow or any symlink set up as long as you are using git.\nIt is easy to migrate to any system with minimal set up required. In addition, with a simple flag `--git`, you can\nnow also use `dotbare` as a generic fuzzy git client to manage any git repository.\n\n## Install\n\n### zsh\n\n`dotbare` should work with any zsh plugin manager, below is only demonstration. Checkout [wiki](https://github.com/kazhala/dotbare/wiki/Completion#zsh)\nabout how to enable completion for zsh.\n\n#### zinit\n\n```sh\nzinit light kazhala/dotbare\n```\n\n#### Fig\n\n[Fig](https://fig.io) adds apps, shortcuts, and autocomplete to your existing terminal.\n\nInstall `dotbare` in just one click.\n\n\u003ca href=\"https://fig.io/plugins/other/dotbare_kazhala\" target=\"_blank\"\u003e\u003cimg src=\"https://fig.io/badges/install-with-fig.svg\" /\u003e\u003c/a\u003e\n\n\n#### oh-my-zsh\n\n- Clone the repository in to [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) plugins directory.\n\n  ```sh\n  git clone https://github.com/kazhala/dotbare.git $HOME/.oh-my-zsh/custom/plugins/dotbare\n  ```\n\n- Activate the plugin in `~/.zshrc`.\n\n  ```zsh\n  plugins=( [plugins...] dotbare [plugins...] )\n  ```\n\n#### Antigen\n\n```sh\nantigen bundle kazhala/dotbare\n```\n\n#### Manual\n\n- Clone the repository (change ~/.dotbare to the location of your preference).\n\n  ```sh\n  git clone https://github.com/kazhala/dotbare.git ~/.dotbare\n  ```\n\n- Put below into `.zshrc`.\n\n  ```sh\n  source ~/.dotbare/dotbare.plugin.zsh\n  ```\n\n### bash\n\n`dotbare` comes with a `dotbare.plugin.bash` which contains the command line completion\nfunction for both `git` and `dotbare`, checkout [wiki](https://github.com/kazhala/dotbare/wiki/Completion#bash)\nabout how to enable it.\n\n- Clone the repository (change ~/.dotbare to the location of your preference).\n\n  ```sh\n  git clone https://github.com/kazhala/dotbare.git ~/.dotbare\n  ```\n\n- Put below into `.bashrc` or `.bash_profile`.\n\n  ```sh\n  source ~/.dotbare/dotbare.plugin.bash\n  ```\n\n### others\n\n1. Clone the repository (change ~/.dotbare to the location of your preference).\n\n   ```sh\n   git clone https://github.com/kazhala/dotbare.git ~/.dotbare\n   ```\n\n2. Add `dotbare` to your PATH.\n\n   ```sh\n   # This is only an example command for posix shell\n   # If you are on fish, use the fish way to add dotbare to your path\n   export PATH=$PATH:$HOME/.dotbare\n   ```\n\n   Or you could create a alias which point to dotbare executable.\n\n   ```sh\n   alias dotbare=\"$HOME/.dotbare/dotbare\"\n   ```\n\n## Getting started\n\n### Dependencies\n\nYou will need git on the system for obvious reasons..and because `dotbare` is written in bash,\nit will require you to have bash in the system (You don't need to run bash, just need to be in the system).\n\n#### Required dependency\n\n- [fzf](https://github.com/junegunn/fzf)\n\n#### Optional dependency\n\n- [tree](https://linux.die.net/man/1/tree) (Provide a directory tree view when finding directory)\n\n  ```sh\n  # if you are on macos\n  brew install tree\n  ```\n\n- [bat](https://github.com/sharkdp/bat) or [highlight](http://www.andre-simon.de/doku/highlight/en/highlight.php) or [coderay](https://github.com/rubychan/coderay)\n  or [rougify](https://github.com/rouge-ruby/rouge) (Syntax highlighting when previewing files, otherwise cat will be used)\n- [delta](https://github.com/dandavison/delta) or [diff-so-fancy](https://github.com/so-fancy/diff-so-fancy)\n  or any diff tools of your choice (Fancy git diff preview like in the screen shot)\n\n### Setup\n\n1. init git bare repository.\n\n   Note: by default, `dotbare finit` will set up a bare repository in \\$HOME/.cfg, to customize\n   location and various other settings, checkout [customization](#customization)\n\n   ```sh\n   dotbare finit\n   ```\n\n2. add dotfiles you want to track.\n\n   Treat `dotbare` as normal `git` commands.\n\n   ```sh\n   dotbare fadd -f\n   # or\n   dotbare add [FILENAME]\n\n   # add entire repository like .config directory\n   dotbare fadd -d\n   # or\n   dotbare add [DIRECTORY]\n   ```\n\n3. commit changes and push to remote.\n\n   ```sh\n   dotbare commit -m \"First commit\"\n   dotbare remote add origin [URL]\n   dotbare push -u origin master\n   ```\n\n### Migration\n\n#### Migrating from normal git bare repository\n\n1. follow the steps in [install](#install) to install `dotbare`.\n2. check your current alias of git bare reference.\n\n   ```sh\n   # Below is an example alias, check yours for reference\n   alias config=/usr/bin/git --git-dir=$HOME/.cfg --work-tree=$HOME\n   ```\n\n3. set env variable for `dotbare`.\n\n   ```sh\n   export DOTBARE_DIR=\"$HOME/.cfg\"\n   export DOTBARE_TREE=\"$HOME\"\n   ```\n\n4. remove the original alias and use `dotbare`.\n\n5. optionally you could alias `config` to `dotbare` so you keep your muscle memory.\n\n   ```sh\n   alias config=dotbare\n   ```\n\n#### Migrating from a generic symlink setup or GNU stow\n\n##### Keep your current setup but integrate dotbare\n\n1. follow the steps in [install](#install) to install `dotbare`.\n2. set environment variable so that `dotbare` knows where to look for git information.\n\n   ```sh\n   # e.g. I have all my dotfiles stored in folder $HOME/.myworld and symlinks all of them to appropriate location.\n   # export DOTBARE_DIR=\"$HOME/.myworld/.git\"\n   # export DOTBARE_TREE=\"$HOME/.myworld\"\n   export DOTBARE_DIR=\u003cPath to your .git location\u003e\n   export DOTBARE_TREE=\u003cPath to directory which contains all your dotfiles\u003e\n   ```\n\n3. Run `dotbare` anywhere in your system.\n\nNote: with this method, you do not run `dotbare finit -u [URL]` when migrating to new system,\nyou will do your normal migration steps and then do the above steps.\n\n##### Complete migration\n\nWhile bare method is great and easy, I recommend keeping your current symlink/GNU stow setup and integrate it with `dotbare` instead of a migration.\nIf you are really happy with `dotbare`, as long as your remote repository resembles the structure of your home holder\n(reference what I mean in my [repo](https://github.com/kazhala/dotfiles.git)), simply run the command below.\n\n**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.\nI recommend you test this migration in docker, see [Test-it-in-docker](#test-it-in-docker).\n\n```sh\n# dotbare will replace all symlinks with the original file and a bare repository will be created at $DOTBARE_DIR\ndotbare finit -u [URL]\n```\n\n#### Migrating dotbare to a new system\n\n1. follow the steps in [install](#install) to install `dotbare`.\n2. Optionally set env variable to customize `dotbare` location (checkout [customization](#customization)).\n\n   ```sh\n   export DOTBARE_DIR=\"$HOME/.cfg\"\n   export DOTBARE_TREE=\"$HOME\"\n   ```\n\n3. give `dotbare` your remote URL and let it handle the rest.\n\n   ```sh\n   dotbare finit -u https://github.com/kazhala/dotfiles.git\n   ```\n\n#### Test it in docker\n\nWhen you are about to do migrations, I strongly suggest you give the migration a try in docker first.\nThe `dotbare` image is based on alpine linux.\n\n```sh\ndocker pull kazhala/dotbare:latest\ndocker container run -it --rm --name dotbare kazhala/dotbare:latest\n```\n\n![migration demo](https://user-images.githubusercontent.com/43941510/82392054-3ee96600-9a86-11ea-9ea9-158452c62d06.gif)\n\n## Customization\n\n`dotbare` could be customized through modification of env variables.\n\nNote: customization of fzf is not covered here, checkout their [wiki](https://github.com/junegunn/fzf/wiki).\n\n### DOTBARE_DIR\n\nThis is the location of the bare repository, `dotbare` will look for this directory\nand query git information or it will create this directory when initializing `dotbare`.\nChange this to location or rename the directory to your liking.\n\nIf you are using symlink/GNU stow setup, set this variable point to the .git folder\nwithin your dotfile directory.\n\n```sh\n# Default value\nexport DOTBARE_DIR=\"$HOME/.cfg\"\n```\n\n### DOTBARE_TREE\n\nThis is the working tree for the git bare repository, meaning this is where the version\ncontrol will take place. I don't recommend changing this one unless **ALL** of your config\nfile is in something like \\$XDG_CONFIG_HOME. If you are using symlink/GNU stow setup,\nset this variable to point to the folder containing all of your dotfiles.\n\n```sh\n# Default value\nexport DOTBARE_TREE=\"$HOME\"\n```\n\n### DOTBARE_BACKUP\n\nThis variable is used to determine where to store the backup of your files. It is used\nmainly by `dotbare fbackup` which will back up all of your tracked dotfiles into this location.\nIt is also used by `dotbare finit -u [URL]`, when there is checkout conflict, `dotbare` will\nautomatically backup conflicted files to this location.\n\n```sh\n# Default value\nexport DOTBARE_BACKUP=\"${XDG_DATA_HOME:-$HOME/.local/share}/dotbare\"\n```\n\n### EDITOR\n\nThis is probably already set in your ENV. `dotbare` uses this variable to determine\nwhich editor to use when running `dotbare fedit`.\n\n```sh\n# Default value\nexport EDITOR=\"vim\"\n```\n\n### DOTBARE_KEY\n\nThis variable set default keybinds for fzf in `dotbare`. You could checkout a list of keybinds\nto set [here](https://github.com/junegunn/fzf/blob/97a725fbd0e54cbc07e4d72661ea2bd2bb7c01c1/man/man1/fzf.1#L648).\n\n```sh\n# Default value\nexport DOTBARE_KEY=\"\n  --bind=alt-a:toggle-all       # toggle all selection\n  --bind=alt-j:jump             # label jump mode, sort of like vim-easymotion\n  --bind=alt-0:top              # set cursor back to top\n  --bind=alt-s:toggle-sort      # toggle sorting\n  --bind=alt-t:toggle-preview   # toggle preview\n\"\n```\n\n### DOTBARE_FZF_DEFAULT_OPTS\n\nCustomize fzf settings for dotbare. This is useful when you want a different\nfzf behavior from your normal system fzf settings.\n\n```sh\n# By default this variable is not set\n# More settings checkout fzf man page and their wiki\n# Example: if you want your preview window for dotbare to be bigger\nexport DOTBARE_FZF_DEFAULT_OPTS=\"--preview-window=right:65%\"\n```\n\n### DOTBARE_PREVIEW\n\nThis variable determines the preview command for file previews. By default, the preview is automatically determined\nusing fall back (bat -\u003e highlight -\u003e coderay -\u003e rougify -\u003e cat). Set this variable to control the preview command if\nyou have a specific preference or if you want extra flags/settings. Reference [here](https://github.com/kazhala/dotbare/blob/master/helper/preview.sh).\n\n```sh\n# By default this value is not set, dotbare uses a fall back method to determine which command to use.\n# Make sure to have \"{}\" included when customizing it, the preview script substitute \"{}\" for actual filename.\n# Example: enable line number for cat command\nexport DOTBARE_PREVIEW=\"cat -n {}\"\n```\n\n### DOTBARE_DIFF_PAGER\n\nThis variable controls the diff output pager in previews like `dotbare flog`, `dotbare fadd` etc. It will read the value\nof `git config core.pager` to determine the pager to use. If you have a specific preference for `dotbare` or have not set\nthe global pager in git config, you could use this variable to customize the diff preview.\n\n```sh\n# By default this value uses fall back (git config core.pager -\u003e cat)\nexport DOTBARE_DIFF_PAGER=\"delta --diff-so-fancy --line-numbers\"\n```\n\n## Usage\n\nAll usage and commands are documented in **[wiki](https://github.com/kazhala/dotbare/wiki/Commands)**.\n\n- [Commands](https://github.com/kazhala/dotbare/wiki/Commands)\n- [Completion](https://github.com/kazhala/dotbare/wiki/Completion)\n- [Custom Scripts and API](https://github.com/kazhala/dotbare/wiki/Custom-Scripts)\n- [Tips and Tricks](https://github.com/kazhala/dotbare/wiki/Tips-and-Tricks)\n\n## Changes\n\nLatest changes are documented in [CHANGELOG](https://github.com/kazhala/dotbare/blob/master/CHANGELOG.md).\n\n## Testing\n\n`dotbare` is unit tested using [bats](https://github.com/bats-core/bats-core). Mock tests are implemented using PATH override method.\nThis is documented [here](https://github.com/kazhala/dotbare/blob/master/tests/README.md) for better readability and extensibility.\n\nNot all functions have 100% coverage and lots of user interaction cannot be effectively tested, please fire up issues if something went wrong.\n\nI'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\nyou could checkout my cloudformation [template](https://github.com/kazhala/AWSCloudFormationStacks/blob/master/CICD_dotbare.yaml).\n\n## Contributing\n\nCheckout out [CONTRIBUTING.md](https://github.com/kazhala/dotbare/blob/master/CONTRIBUTING.md) to see how you could contribute to `dotbare`. PRs are\nwelcome and I'm happy to improve/extend `dotbare`'s functionality.\n\nDon't forget to leave a star :)\n\n## Background\n\n`dotbare` was initially part of my personal scripts, I had a hard time sharing those scripts\nand as the number of scripts grows, I feel like is more appropriate to make a dedicated project\nfor it. I hope you find it useful and enjoy it, thanks!\n\n## Credit\n\n- credit to [forgit](https://github.com/wfxr/forgit) for inspiration.\n- credit to [fzf](https://github.com/junegunn/fzf) for fzf and the preview script from fzf.vim.\n- credit to [OMZ](https://github.com/ohmyzsh/ohmyzsh) for upgrading method.\n- credit to [this](https://www.atlassian.com/git/tutorials/dotfiles) post for step by step guide of setting up git bare repo.\n- credit to [this](https://www.youtube.com/watch?v=tBoLDpTWVOM\u0026t=288s) video for introducing git bare repo.\n\n## Demo\n\nYou could find some more demo [here](https://github.com/kazhala/dotbare/issues/1)\n[![asciicast](https://asciinema.org/a/332231.svg)](https://asciinema.org/a/332231)\n","funding_links":[],"categories":["Plugins","Shell","bash","Tools"],"sub_categories":["ZSH on Windows","Ansible"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazhala%2Fdotbare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkazhala%2Fdotbare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazhala%2Fdotbare/lists"}