DOCSEARCHbyAlgolia
Submit Docs

dotbare

repository·master·Indexed 20 days ago

https://github.com/kazhala/dotbare

A command-line utility for managing dotfiles using a git bare repository. It provides an interactive, fzf-powered interface for git operations, allowing users to manage system configuration files in their natural locations without symlinks. It can also function as a generic fuzzy git client for any standard git repository using the --git flag.

Tokens
2.6K
Snippets
15
Records
18
Agent score
23%

What's inside dotbare

  1. What is dotbare?

    master

    Overview

    dotbare is a command line utility designed to manage dotfiles using a git bare repository. It provides an interactive experience by wrapping git commands and displaying information through fzf.

    Key Use Cases

    • Dotfile Management: Manages system dotfiles without using symlinks (e.g., GNU Stow), keeping files in their natural locations.
    • Generic Fuzzy Git Client: By using the --git flag, dotbare can be used as a fuzzy git client for any standard git repository by dynamically determining the top-level .git folder.

    Core Features

    • Interactive UI: Uses fzf for selecting and editing files (fedit), staging/unstaging files (fstat), and viewing logs (flog).
    • Command Completion: Supports command line completion for both git and dotbare commands.
    • Integration: Can integrate with existing symlink or GNU Stow setups.

  2. Quickstart: Set up dotfile management with dotbare

    master

    Follow these steps to initialize a git bare repository for your dotfiles and start tracking them.

    1. Initialize the bare repository: By default, dotbare finit sets up a bare repository in $HOME/.cfg.
    dotbare finit
    1. Add dotfiles: Use fadd for interactive adding or standard add commands.
    # Interactive add
dotbare fadd -f

# Add a specific file
dotbare add [FILENAME]

# Add an entire directory (e.g., .config)
dotbare fadd -d
# or
dotbare add [DIRECTORY]
    1. Commit and Push:
    dotbare commit -m "First commit"
dotbare remote add origin [URL]
dotbare push -u origin master
    dotbare finit
dotbare fadd -d
dotbare commit -m "Initial commit"

  3. Test migrations in Docker

    master

    Before performing a major migration (especially the complete migration), it is highly recommended to test the process in a containerized environment using the official dotbare image.

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

  4. Install dotbare for zsh

    master

    You can install dotbare using various zsh plugin managers or manually.

    Using Zinit

    zinit light kazhala/dotbare

    Using Oh My Zsh

    1. Clone the repository into your custom plugins directory:
    git clone https://github.com/kazhala/dotbare.git $HOME/.oh-my-zsh/custom/plugins/dotbare
    1. Add dotbare to your plugins list in ~/.zshrc:
    plugins=( [plugins...] dotbare [plugins...] )

    Using Antigen

    antigen bundle kazhala/dotbare

    Manual Installation

    1. Clone the repository to your preferred location (e.g., ~/.dotbare):
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
    1. Source the plugin in your ~/.zshrc:
    source ~/.dotbare/dotbare.plugin.zsh
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
source ~/.dotbare/dotbare.plugin.zsh

  5. Configure dotbare dependencies

    master

    To get the best experience, ensure the following dependencies are installed:

    Required

    • fzf: Essential for the interactive UI.
    • git: Required for all operations.
    • bash: dotbare is written in bash.

    Optional (Enhancements)

    • tree: Provides directory tree views when finding directories (brew install tree on macOS).
    • Syntax Highlighting: Use bat, highlight, coderay, or rougify for file previews.
    • Diff Tools: Use delta or diff-so-fancy for enhanced git diff previews.

  6. Install dotbare for bash

    master

    To install dotbare for bash, clone the repository and source the bash plugin.

    1. Clone the repository (replace ~/.dotbare with your preferred path):
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
    1. Add the following to your .bashrc or .bash_profile:
    source ~/.dotbare/dotbare.plugin.bash
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
source ~/.dotbare/dotbare.plugin.bash

  7. Migrate from symlink/GNU Stow setup to dotbare

    master

    You have two options when migrating from a symlink-based setup.

    Option 1: Integrate dotbare (Recommended)

    Keep your current symlink setup but use dotbare to interact with the underlying git repository.

    1. Install dotbare.
    2. Set environment variables so dotbare knows where your git info and dotfiles are located:
      # Example: dotfiles are in $HOME/.myworld and symlinked to $HOME
export DOTBARE_DIR="$HOME/.myworld/.git"
export DOTBARE_TREE="$HOME/.myworld"
    3. Run dotbare commands from anywhere.

    Option 2: Complete Migration (Convert symlinks to bare repo)

    Warning: This replaces symlinks with original files and creates a bare repository. Use with caution and test in Docker first.

    # This will replace symlinks with original files and create a bare repository at $DOTBARE_DIR
dotbare finit -u [URL]
    # Integration method
export DOTBARE_DIR="<Path to your .git location>"
export DOTBARE_TREE="<Path to directory containing dotfiles>"

  8. Migrate from a normal git bare repository to dotbare

    master

    If you already have a git bare repository setup (e.g., using an alias like config), follow these steps to switch to dotbare:

    1. Install dotbare as described in the installation guide.
    2. Identify your current git bare reference (e.g., alias config=/usr/bin/git --git-dir=$HOME/.cfg --work-tree=$HOME).
    3. Set the required environment variables for dotbare:
      export DOTBARE_DIR="$HOME/.cfg"
export DOTBARE_TREE="$HOME"
    4. Remove your old alias and use dotbare instead.
    5. (Optional) Alias your old command to dotbare to maintain muscle memory:
      alias config=dotbare
    export DOTBARE_DIR="$HOME/.cfg"
export DOTBARE_TREE="$HOME"
alias config=dotbare

  9. Install dotbare for other shells (POSIX/Fish)

    master

    For other shells, clone the repository and add it to your PATH or create an alias.

    1. Clone the repository:
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
    1. Add to PATH (Example for POSIX shells):
    export PATH=$PATH:$HOME/.dotbare

    Note: If you are using fish, use the standard fish way to add a directory to your path.

    Alternatively, create an alias:

    alias dotbare="$HOME/.dotbare/dotbare"
    git clone https://github.com/kazhala/dotbare.git ~/.dotbare
export PATH=$PATH:$HOME/.dotbare

  10. Configure DOTBARE_BACKUP

    master

    Set DOTBARE_BACKUP to determine where to store backups. This directory is used by:

    1. dotbare fbackup: Backs up all tracked dotfiles to this location.
    2. dotbare finit -u [URL]: Automatically backs up conflicted files during checkout conflicts.
    # Default value
export DOTBARE_BACKUP="${XDG_DATA_HOME:-$HOME/.local/share}/dotbare"

  11. Customize dotbare via environment variables

    master
    You can customize the behavior of dotbare by setting specific environment variables in your shell configuration. This allows you to control repository locations, backup paths, editor preferences, and UI settings for fzf and previews.

  12. Configure DOTBARE_DIFF_PAGER

    master

    Set DOTBARE_DIFF_PAGER to control the diff output pager used in previews (e.g., during dotbare flog or dotbare fadd).

    Default Behavior: It falls back to git config core.pager, and if that is not set, it uses cat.

    export DOTBARE_DIFF_PAGER="delta --diff-so-fancy --line-numbers"