macOS · Git · GitHub

How to Manage Your macOS Dotfiles with Git and GitHub

Your dotfiles shape how your shell, editor, Git setup, and other developer tools behave. When you store them in Git and back them up on GitHub, your environment becomes easier to track, easier to restore, and much easier to move to a new Mac.

What you’ll learn

Create a dedicated dotfiles repository, organize files around your real macOS layout, and activate them with symlinks.

Why it matters

A good dotfiles workflow turns your setup from fragile customization into a repeatable system you can rebuild with confidence.

End result

One repository becomes the source of truth for your development environment, complete with version history and backup.

Quick takeaway Git gives your configuration history. GitHub gives it an off-machine backup. Together, they make your setup easier to maintain, recover, and reuse.

Foundation

Why dotfiles are worth managing

Dotfiles are hidden configuration files that control how your tools behave day to day. They often define shell startup behavior, aliases, Git preferences, editor settings, plugin configuration, and the small defaults that make your environment feel like yours.

Once you customize those tools, the config files stop being incidental. They become part of your working environment. Putting them in Git gives you history, safer edits, and a practical way to understand what changed over time.

What changes once you version them

Instead of rebuilding your setup from memory, you can clone a repository, relink your files, and restore the parts of your workflow that matter most. That is the real value: repeatability.

Before you start

Begin with the files that actually matter

You do not need to migrate everything on day one. Start with the files that have the biggest effect on your daily workflow, then expand the repository as your setup becomes more stable.

Do not commit secrets Keep tokens, private keys, local machine credentials, and other sensitive values out of the repository. Dotfiles are ideal for configuration, not for secrets.

Good first files	Why they belong
.zshrc	Controls shell behavior, aliases, environment setup, and prompt-related customization.
.gitconfig	Keeps Git identity, aliases, defaults, and quality-of-life preferences consistent.
Editor settings	Preserves the editing experience you rely on every day, especially in Neovim or VS Code.

Step 1

Create a dedicated repository

Give your configuration its own project. Keeping dotfiles in a separate repository makes them easier to reason about, easier to back up, and easier to carry between machines.

gh auth login
gh repo create

Once the repository exists, start adding the files you want to track and commit them the same way you would any other project.

Step 2

Mirror your real config structure

A clean dotfiles repository usually follows the same layout your system and tools already expect. That keeps the repo intuitive and makes installation much easier later.

dotfiles/
├── .zshrc
├── .gitconfig
├── .config/
│   └── nvim/
│       ├── init.lua
│       ├── keymaps.lua
│       ├── options.lua
│       ├── plugins.lua
│       └── lsp/
│           └── init.lua
└── Makefile

This structure keeps related configuration together without inventing a layout that only makes sense inside the repository.

Step 3

Use symlinks so the repo stays in control

A practical pattern is to keep the real files inside your dotfiles repository and create symbolic links where macOS or your tools expect to find them.

That way, the repository remains the single source of truth. You edit the files in one place, while your shell, Git, and editor continue reading them from their usual paths.

Why symlinks are a strong default Symlinks are usually easier to recreate and easier to reason about than hardlinks in a dotfiles setup, especially once nested config directories are involved.

Step 4

Automate installation with a Makefile

A dotfiles repository becomes much more useful when setup is repeatable. A simple Makefile is often enough to create the necessary directories and refresh the links you need.

install:
	mkdir -p ~/.config/nvim
	ln -sf $(PWD)/.zshrc ~/.zshrc
	ln -sf $(PWD)/.gitconfig ~/.gitconfig
	ln -sf $(PWD)/.config/nvim/init.lua ~/.config/nvim/init.lua
	ln -sf $(PWD)/.config/nvim/keymaps.lua ~/.config/nvim/keymaps.lua
	ln -sf $(PWD)/.config/nvim/options.lua ~/.config/nvim/options.lua
	ln -sf $(PWD)/.config/nvim/plugins.lua ~/.config/nvim/plugins.lua

Running make install recreates the expected structure and relinks your files in one step, which is especially useful on a fresh Mac or after a reinstall.

Workflow summary

The process at a glance

Step	Action	Why it helps
1	Create a repository	Gives your configuration a dedicated project and commit history.
2	Organize by real usage	Keeps the repository aligned with the file paths your tools already use.
3	Link files into place	Lets the repo remain the source of truth without breaking expected paths.
4	Push to GitHub	Creates a backup and makes the setup easier to restore on another Mac.

Why this pays off

What improves over time

Managing dotfiles this way gives you more than backup. It gives your environment continuity.

• Safer edits, because every meaningful change has history
• Faster machine setup, because installation becomes repeatable
• Cleaner organization, because config lives in one managed place
• Better portability, because your environment can move with the repository

A useful rule of thumb If a config file meaningfully affects how you work and you would miss it on a new machine, it probably belongs in your dotfiles repository.

FAQ

Frequently Asked Questions

These are the practical questions most people have when they start managing macOS dotfiles with Git and GitHub.

What are dotfiles on macOS?

Dotfiles are configuration files, usually hidden because their names begin with a period, that control how tools like Zsh, Git, Neovim, and other developer apps behave.

Why should I store dotfiles in Git?

Git gives your configuration history. That means you can track changes, roll back mistakes, and understand how your setup evolved over time.

Why use GitHub too?

GitHub gives you an off-machine backup and makes it much easier to restore your setup on a new Mac or after a reinstall.

Should I commit every config file right away?

No. It is better to start with the files that have the biggest impact on your daily workflow, such as .zshrc, .gitconfig, and your editor settings.

Is it safe to put dotfiles on GitHub?

Yes, as long as you keep secrets out of the repository. Never commit API keys, private keys, tokens, passwords, or machine-specific sensitive data.

Why use symlinks for dotfiles?

Symlinks let your repository remain the single source of truth while your tools still read files from the paths they expect. That makes the setup easier to manage and recreate.

Do I need a Makefile?

Not strictly, but it helps a lot. A simple Makefile makes installation repeatable, which is one of the main reasons to manage dotfiles this way in the first place.

What is the biggest benefit of a dotfiles repository?

The biggest benefit is repeatability. You stop rebuilding your environment from memory and start treating it like a real system you can restore with confidence.

Final thought

Dotfiles may look small, but they define a large part of your development environment. Once you manage them with Git and GitHub, your setup becomes easier to understand, easier to restore, and easier to improve over time.

The biggest benefit is not just backup. It is having a workflow you can reproduce, trust, and carry forward to the next machine.

View the dotfiles repository

Raell Dottin