A Brief Guide To Manage Dotfiles
Tags: dotfiles, tutorial, programming, linux
Published: 2022-02-15 12:36:21

There is a bazillion of tutorials and resources on how to manage dotfiles out there. If you haven’t heard of “dotfiles”, they are basically config files in Unix-like systems that start with a dot, e.g. `.bashrc`, `.zshrc`, `.vimrc`, `.gitconfig` just to name a few.

By default, dotfiles are hidden and they are typically used to customize your system.

Why bother? Well, having your personal dotfiles up on the cloud makes it incredibly easy for you to set up any new environment, like in the case of getting a new laptop, etc.

### Prerequisites

-   A Git hosting service account, e.g. [GitHub](https://github.com/)
-   [Git](https://git-scm.com/) and basic knowledge of how to use it
-   Basic Linux commands

## Pain Points

The dotfiles community is huge.

As an average Linux user, my developer tool customization outside of VSCode is a total mess. I see [gorgeous dotfiles](https://dotfiles.github.io/inspiration/) being shared everywhere around the Internet. They are so fascinating, intriguing yet daunting at times.

After spending hours reading, looking around elegant [dotfiles repositories](https://github.com/search?q=dotfiles&type=Repositories), this article aims to get you started on managing your own dotfiles as painlessly as possible.

## The Tradition

Generally, dotfiles are managed in a separate Git directory, usually called `~/.dotfiles`. You will then have to create symlinks from there to the original location of the respective dotfile (usually your home directory).

Finally, the dotfiles are then committed and pushed to the Git hosting service of your choice, e.g. a public GitHub repository, [just like this](https://github.com/ngshiheng/dotfiles).

To gain more context, I’d highly recommend you to [read this article](https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789) to understand how dotfiles are typically managed.

## Getting Started With Chezmoi

Today, we will look into abstracting most of that hassle of managing your dotfiles.

In my quest of looking for a straightforward solution to manage my dotfiles, I found [chezmoi](https://chezmoi.io/). With chezmoi, you can ignore the part where you manually create symlinks. If you need more convincing, do check out [why use chezmoi](https://www.chezmoi.io/why-use-chezmoi/).

What follows is the step-by-step guide on how to start using chezmoi to manage your dotfiles.

![Flow Chart of Getting Started With Chezmoi](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a4ui7f1ufrfg3iavpc9z.png)

### 1. Creating a GitHub repository

Before we begin, you’ll need to [create a new GitHub repository](https://github.com/new).

By convention, the repository name to manage dotfiles is often called `.dotfiles` or just `dotfiles`. Here, I’ll assume that you name your dotfile repository as `dotfiles`.

Don’t get me wrong, chezmoi can also be used with other Git hosting services like [GitLab](https://gitlab.com/) or [BitBucket](https://bitbucket.org/).

### 2. Installation

Installing chezmoi is easy, simply follow the installation steps [here](https://www.chezmoi.io/install/) based on the package manager of your choice. A quick one-line installation would be:

```bash
sh -c "$(curl -fsLS chezmoi.io/get)"
```

### 3. Init

Remember how dotfiles are managed in a Git directory? Simply run `chezmoi init` to create a new Git directory in `~/.local/share/chezmoi` (source directory in the following) where chezmoi stores its source state.

Later on, you will have to perform Git commit and push any new changes that you make to the source state just like a normal project in any Git repository.

### 4. Adding your first dotfile

Before we start, do always keep in mind that the first rule of managing your dotfile is to never push any secrets (e.g. API keys, AWS credentials) to any public repository (not even to private repositories!) in plain text.

In this article, I will be using `.zshrc` as our example dotfile of choice. In practice, feel free to add multiple dotfiles at once. So, let’s start to manage your first dotfile by “adding” it!

To add your `.zshrc` file which is typically located at our home directory, run:

```bash
# This will copy ~/.zshrc to our source directory at ~/.local/share/chezmoi/dot_zshrc
chezmoi add  ~/.zshrc
```

Remember this — chezmoi only modifies the files in the working copy, you will have to commit and push any changes yourself (though [chezmoi can automate this](https://www.chezmoi.io/user-guide/daily-operations/#automatically-commit-and-push-changes-to-your-repo)).

To go to your source directory, simply run:

```bash
chezmoi cd # Same as running cd ~/.local/share/chezmoi/dot_zshrc
```

Here, you will see your `.zshrc` file as `dot_zshrc`.

### 5. Committing and pushing to GitHub

Sounding like a broken record — please make sure that you do not commit any secrets or credentials as plain text.

From here on, it’s like committing and pushing any regular Git projects that you have:

```bash
git remote add origin git@github.com:your-awesome-username/dotfiles.git
git branch -M main

git add .
git commit -m "<Initial commit message>"
git push -u origin main
```

Yay! Now you have your dotfile on your GitHub repository!

## Maintaining Dotfiles

We will never be satisfied with what we have. There will always be _more_ customizations. New files. Updates. Changes.

One important concept — to make any changes to your dotfile, always modify it at your source directory (e.g. `~/.local/share/chezmoi/dot_zshrc`); NOT the original dotfile (e.g. `~/.zshrc`).

You can imagine modifying anything inside your source directory to be the equivalent of updating the state that you want to store in your public repository.

![Flow Chart of Managing Dotfiles](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1ym2robha3szk8zgiohl.png)

### 1. Where to make changes

To modify the source state, you can either:

-   Update the source state dotfile directly at `~/.local/share/chezmoi/dot_zshrc` OR
-   A quick way to do so is to use the `chezmoi edit ~/.zshrc` command

### 2. How to edit your dotfiles

Once you’re satisfied with your changes, save your dotfile and run:

```bash
# To view the diff between ~/.local/share/chezmoi/dot_zshrc & ~/.zshrc
chezmoi diff

# To apply the changes to your original ~/.zshrc
chezmoi -v apply
```

The `apply` command above will make changes to your original dotfile at your home directory, i.e. `~/.zshrc` in this case.

### 3. Committing and pushing to GitHub (again)

Finally, to update your changes on your dotfile repository, simply run:

```bash
git add .
git commit -m "<Your update commit message>"
git push -u origin main
```

Great! You have just successfully updated your dotfile on your GitHub repository!

## Adding New File

Adding new dotfiles is easy. Unlike “Maintaining Dotfiles” where you have to do `chezmoi diff` and `apply`, you simply follow the steps below:

1. `chezmoi add ~/.newdotfile`
2. `chezmoi cd`
3. `git add .`
4. `git commit -m "<New dotfile commit message>"`
5. `git push -u origin main`
6. Done!

## Using Your Dotfiles

Now that we have our dotfiles hosted on our GitHub repository, we shall look into how to use them on another machine.

On a separate machine, initialize chezmoi with your dotfiles repository by simply running:

```bash
sh -c "$(curl -fsLS chezmoi.io/get)" -- init --apply your-awesome-username
```

Remember — before you apply any changes to your local dotfiles at this machine, run `chezmoi diff` to view diff between the dotfiles at `~/.local/share/chezmoi/` and their original location.

If the diff is what you expect to see, run `chezmoi apply -v` to override your local dotfiles.

At any time — to pull and apply the latest changes from your dotfiles repository, run:

```bash
chezmoi update -v
```

## Closing Thoughts

Managing your dotfile helps to carry your customization with you everywhere you go. To be frank, there is no “best way” to manage your dotfiles. Using chezmoi appeared to be the simplest solution for my laziness, and it just works.

Honestly, I am barely scratching the surface of what chezmoi is capable of. In case you want to dive deeper, I’d highly recommend you to check out [chezmoi’s user guide](https://www.chezmoi.io/user-guide/setup/).

That’s all I have for today and thanks for reading!

---

_This article was originally published on [jerrynsh.com](https://jerrynsh.com/how-to-manage-dotfiles-with-chezmoi/)_