necolas/dotfiles — 796★ on GitHub (Shell). OS X dotfiles: bash, git, vim, etc.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
N.B. If you wish to fork this project and maintain your own dotfiles, you must
substitute my username for your own in the above command and the 2 variables
found at the top of the bin/dotfiles script.
What the installation does
The installation script performs the following steps in order:
Prompts for install location (defaults to ~/.dotfiles, or uses existing config)
Saves config to ~/.config/dotfiles/config for future runs
Downloads the repository to your chosen location (if not already present)
Installs Homebrew (if not already installed)
Installs Git via Homebrew (if not already installed)
Initializes a Git repository and connects it to the remote
Syncs with the remote repository to get the latest changes
Installs packages via Homebrew
Creates symlinks from your home directory to the dotfiles:
~/.curlrc → <dotfiles>/shell/curlrc
~/.gitattributes → <dotfiles>/git/gitattributes
~/.gitignore → <dotfiles>/git/gitignore
~/.gvimrc → <dotfiles>/vim/gvimrc
~/.vim → <dotfiles>/vim
~/.vimrc → <dotfiles>/vim/vimrc
~/.zprofile → <dotfiles>/shell/zprofile
~/.zshenv → <dotfiles>/shell/zshenv
Adds a hook to the top of ~/.zshrc (see Hooked
files)
Asks for your git author identity and writes it to ~/.gitconfig, with an
[include] of <dotfiles>/git/gitconfig (see Git identity)
Applies macOS defaults (optional, with confirmation prompt)
Custom install location
On first run, the script will prompt you for an install location:
Where would you like to install dotfiles?
Install location [~/.dotfiles]: ~/Code/dotfiles
Press Enter to accept the default (~/.dotfiles) or enter a custom path.
The chosen location is saved to ~/.config/dotfiles/config and used for all
future runs.
How to update
You should run the update when:
You want to pull changes from the remote repository.
You want to update Homebrew formulae.
You do not need to run it after editing a file in the repository. Every file
is either symlinked or included, so an edit takes effect in the next shell.
Run the dotfiles command:
$ dotfiles
Options:
-h, --help
Help
-l, --link
Quick update: symlinks only (skips sync, packages, macOS)
--macos
Apply macOS system settings only
Quick updates during local development
When making local changes to your dotfiles, use the quick update mode to apply
changes without syncing or updating packages:
$ dotfiles --link
This refreshes the symlinks and the hooks. It never removes a line that this
repository did not write.
How to use
Hooked files
~/.zshrc and ~/.gitconfig are real files, not symlinks. Each holds a hook at
the top that reads the dotfiles config:
File
Hook
~/.zshrc
sources shell/zshrc
~/.gitconfig
includes git/gitconfig
Other tools write to both files, and an append follows a symlink. A symlink would
send those writes into this repository.
The hook goes at the top. zsh and git both take the last value they read, so a
setting below the hook overrides a dotfiles default. Put your machine-local
settings there.
Git identity
Your name and email live in ~/.gitconfig. That file is not tracked, and this
repository stores no identity. The installer asks once:
Git author identity
Every commit you make carries this name and email.
Name:
Email:
git/gitconfig sets user.useConfigOnly = true. git then refuses to commit until
an identity exists, and never guesses one from the OS. So a forgotten identity
stops the commit. It cannot mislabel one.
Local Vim configuration
Any special-case Vim directives local to a machine should be stored in a
~/.vimrc.local file on that machine. The directives will then be automatically
imported into your master .vimrc.
Features
Automatic software installation
Homebrew formulae:
GNU core utilities
git
node
bun
Custom macOS settings
Custom macOS settings can be applied during the dotfiles process. They can
also be applied independently by running:
$ dotfiles --macos
Bootable backup-drive script
These dotfiles include a script that uses rsync to incrementally back up your
data to an external, bootable clone of your computer's internal drive. First,
make sure that the value of DST in the bin/backup script matches the name
of your backup-drive. Then run the following command:
$ backup
For more information on how to setup your backup-drive, please read the
preparatory steps in this post on creating a bootable macOS backup
drive.
Custom zsh prompt
When your current working directory is a Git repository, the prompt displays the
checked-out branch's name. During a rebase, a merge, or a bisect it also shows
the action, as main|rebase-i. The state of the working tree is reflected in the
following way:
+
Uncommitted changes in the index
!
Unstaged changes
?
Untracked files
$
Stashed files
The prompt is built on zsh's own vcs_info, with one git status call per
prompt. Further details are in the shell/prompt file.
Acknowledgements
Inspiration and code was taken from many sources, including:
The most recent commit recorded on necolas/dotfiles was 2 days ago, based on the GitHub push timestamp. The repository has 140 forks — one of the better signals of community interest.
How many stars does necolas/dotfiles have?
necolas/dotfiles has 796 GitHub stars — refresh the page for the live number, or check github.com/necolas/dotfiles. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is necolas/dotfiles open source?
Yes — necolas/dotfiles ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/necolas/dotfiles.
What is necolas/dotfiles?
necolas/dotfiles (necolas/dotfiles) is a Shell project on GitHub. From the project's own README: OS X dotfiles: bash, git, vim, etc.
Where do I read more about necolas/dotfiles?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/necolas/dotfiles is the definitive source.
Read full README in the tab above.
Curious whether dotfiles is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about dotfiles.