Skip to content
Get packs

Guide · Open source

How to use dotfiles: clone, bootstrap and adapt Mathias's setup

Updated · written with AI from the project's own documentation and checked against our catalogue data

Dotfiles are the hidden configuration files in your home folder that shape your shell, such as ~/.bashrc-style settings and aliases. This guide walks through mathiasbynens/dotfiles, a macOS-focused collection of shell configuration files plus a .macos script that sets system preferences. By the end you will know how to install it, update it, add your own settings, and decide whether to adapt it for your own Mac.

dotfilesmathiasbynens/dotfiles · ★ 31.5k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Git and Bash, and that you are on macOS if you plan to use the .macos and brew.sh scripts.
  2. 2Review the code. Read the files and the warning in the README, then fork the repository and remove anything you do not want.
  3. 3Clone the repository. Clone the repository with git clone, then change into the dotfiles folder.
  4. 4Run the bootstrap script. Run source bootstrap.sh to copy the files into your home folder.
  5. 5Add personal settings. Create ~/.path or ~/.extra for your PATH changes, custom commands and private credentials.
  6. 6Update later. Change into the repository and run source bootstrap.sh again to pull in changes.

What is in the mathiasbynens/dotfiles repository?

This is a collection of shell configuration files that customize the terminal environment on macOS. It also includes a script called .macos that sets many system preferences, and a brew.sh script that installs Homebrew formulae.

The project is written in Shell and released under the MIT licence. The author describes it as a reference and starting point rather than a turnkey tool.

  • Shell configuration files that customize the terminal
  • ~/.macos, a script of sensible macOS defaults
  • brew.sh, a script that installs common Homebrew formulae
  • A bootstrap script that copies the files into your home folder

Check the prerequisites before you start

You need Git and Bash. The .macos and brew.sh scripts are specific to macOS, so they only make sense on a Mac.

Read the warning in the README first: the author advises forking the repository, reviewing the code, and removing anything you do not want. Do not blindly use these settings unless you know what they do.

  • Git
  • Bash
  • macOS for the .macos and brew.sh scripts

Install with Git and the bootstrap script

Clone the repository wherever you want. The bootstrap script pulls in the latest version and copies the files to your home folder. Run this single command from the README:

git clone https://github.com/mathiasbynens/dotfiles.git && cd dotfiles && source bootstrap.sh

Update your dotfiles

To update, change into your local dotfiles repository and run the bootstrap script again. If you want to skip the confirmation prompt, the README shows a variant that sets the -f flag first.

source bootstrap.sh

Add your own settings with ~/.path and ~/.extra

If ~/.path exists, it is sourced with the other files before any feature testing takes place, so it is the place to change your PATH. The README's example adds /usr/local/bin to the PATH.

If ~/.extra exists, it is also sourced. Use it for custom commands or private settings you do not want to commit to a public repository, such as Git credentials. It can also override settings, functions and aliases from the repository, though the author suggests forking instead.

export PATH="/usr/local/bin:$PATH"

Apply macOS defaults and install Homebrew formulae

When setting up a new Mac, you may want to apply the sensible macOS defaults. Run the .macos script only after reviewing it. For common command line tools, install Homebrew first, then run brew.sh.

Some functionality depends on formulae installed by brew.sh. If you skip that script, look through it and install the important ones yourself. The README gives Bash/Git completion as an example, since the dotfiles use a special version from Homebrew.

  • Review ~/.macos line by line before running it
  • Install Homebrew before running brew.sh
  • Install any needed formulae manually if you skip brew.sh
./.macos

What people use it for

  • Study how another developer sets up a shell on macOS
  • Use the repository as a template for a new Mac and adapt it
  • Keep private Git credentials in ~/.extra instead of a public repository
  • Apply a set of macOS system preferences from the .macos script after review

Frequently asked questions

How do I install mathiasbynens dotfiles?

Clone the repository with git clone https://github.com/mathiasbynens/dotfiles.git, change into the dotfiles folder, and run source bootstrap.sh. The bootstrap script copies the files to your home folder. The README also describes a Git-free install using curl and tar.

Do I need Git to use these dotfiles?

No. The README includes a Git-free install that downloads the repository tarball with curl and extracts it with tar into your home folder. To update, you run that command again.

Do these dotfiles work on Linux or Windows?

The README says the macOS defaults script is specific to macOS, and the .macos and brew.sh scripts require macOS. The shell files may be usable elsewhere, but the source does not claim that, so review them before trying.

Are the dotfiles safe to run without reading them?

The author warns against it. The README says you should fork the repository, review the code, and remove things you do not need, and that you should not blindly use the settings unless you understand them. The scripts change system settings and shell behavior.

Where should I put my own settings?

Put PATH changes in ~/.path and custom commands or private values such as Git credentials in ~/.extra. Both files are sourced with the other dotfiles if they exist, so they stay out of the repository.

How does this compare to chezmoi, GNU Stow or yadm?

Those are comparable projects that also manage dotfiles. This repository is a personal, macOS-focused example with a bootstrap script and macOS defaults, rather than a general-purpose manager. The source does not compare features, so check each project's documentation to decide.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this repository if you are a developer on macOS who wants to study or borrow a working shell setup and can read Bash well enough to review each script. Pick a general dotfile manager or a less opinionated template if you are not comfortable changing system settings, or if you use Linux or Windows.

Install options & downloads