Getting started with bare‑repo Linux dotfiles management

In this article, we will organize dotfiles management using the Bare-repo method. There are dotfile management managers such as dotbot / yadm / homeshick / chezmoi, but in the beginning, the bare-repo method, which can be completed with just git, is sufficient. If I ever run into any problems, I will reconsider migrating to dotfile management manager.

Introduction

Version control of dotfiles is essential to maintaining a pleasant long-term development experience. In this article, we will organize the steps to start management at the lowest cost using the Bare-repo method.

• Target audience: People who have just acquired a new Linux environment and want to start managing dotfiles easily.

• Goal :

  1. Initial startup using Bare-repo method possible

  2. Operate daily changes safely

  3. Even if a new machine arrives, you can reproduce the environment with a few commands.

  4. Get information on deciding whether to switch to chezmoi

What is Bare‑repo method?

This is a simple method that uses the home directory as a work tree and treats $HOME/.dotfiles as a bare repository. Sorting out the advantages and disadvantages

Overview of Bare‑repo method

point of view	merit	Disadvantages
Convenience	Complete with just Git, no additional tools required	Commands tend to be long (alias recommended)
portability	Reproduce in other environments with just git clone --bare	Manual management of branches and templates for each OS
security	Easy to exclude private keys etc. (.gitignore)	Care must be taken not to unintentionally push to a public repository

Basic Git settings (first time only)

The following settings only need to be performed once and will be reflected in all Git repositories.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main   # 初期ブランチ名を main に統一

Initial startup procedure

1. Create bare repository

   git init --bare "$HOME/.dotfiles"
   

2. Convenient aliases available

   alias dot='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
   echo "alias dot='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'" >>~/.bashrc
   

3. Adjust Git settings — Hide files that are not under git management

   dot config --local status.showUntrackedFiles no
   

4. First commit & remote registration

   dot remote add origin git@github.com:<YOUR-USER>/dotfiles.git
   dot add ~/.bashrc ~/.gitconfig
   dot commit -m "Initial commit"
   dot push -u origin main
   

Daily operation flow

1. Confirm changes:

   dot status
   

2. Check the difference:

   dot diff <file>
   

3. Add/Commit/Push:

   dot add <file>
   dot commit -m "Update tmux.conf: enable mouse mode"
   dot push
   

4. Handling machine-specific settings

   • Separate to .config/machine-specific/ etc. and register in .git/info/exclude

   • Alternative: Separate Git configuration to load by hostname with includeIf function

New environment setup

Once you’re on a new server or WSL, you can reproduce it just by doing the following:

git clone --bare git@github.com:<YOUR-USER>/dotfiles.git $HOME/.dotfiles
alias dot='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
dot checkout --force
dot config --local status.showUntrackedFiles no

Warning

If dot checkout conflicts with an existing file, it will be overwritten. If you need a backup, check the error list without adding --force, save the relevant files, and try again.

Modernization of existing environment

dot pull --rebase

If there is a Conflicted file, it will be resolved like normal Git.

Other scenes to consider

• Encryption of secrets — combined with pass/git‑crypt/sops

• GUI app settings directory is huge — only partially managed with symbolic links

• Differences by OS/distribution — Branch with Makefile or includeIf

• Automatic sync — GitHub Actions + periodic push/pull with SSH

About dotfile management manager

• There are tools specialized for dotfile management such as dotbot / yadm / homeshick / chezmoi

• chezmoi is especially popular

Note

In the future, if there is a need to increase the amount of confidential information in dotfiles across multiple OSes including Mac and Windows (WSL), consider migrating to an administrative manager.

summary

The bare-repo approach is the fastest way to get started with Git alone. It lets you first get comfortable with the workflow and focus on growing your dotfiles, then consider moving to a dotfiles manager once the setup becomes more complex.

Please note that my current repository URL is below. It’s still under development, but if you’re interested, please take a look.

• mtakagishi’s dotfiles

Reference link

• Atlassian Git Tutorial

• chezmoi official document

Article information

Post date:

2025-05-02

author:

Mr. Takagi

Initial tasks performed in a Linux environment   Modern shell environment setup starting with zsh + starship