These are all the settings you will incrementally set and ultimately forget.
dotfiles attempts to work seamlessly between MacOS and most GNU/Linux
environments.
Additionally, it strictly adheres to the XDG Base Directory Specification ("XDG" or "XDG spec" or "XDG specification").
This is good for anyone who wants a clean ${HOME}, especially MacOS users
who do not natively benefit from the XDG spec.
These dotfiles were originally developed with Homebrew
support. Starting late 2021, a feature branch to support Home Manager with Nix
was developed. As of May 2023, both package managers should be able to operate
in parallel, and these dotfiles will essentially continue to work. Note that if
the relevant Nix environment variables are detected, they will take precedence
when buildling the ${PATH}, which means that packages from Nix will be
prioritized over matching packages from Homebrew.
The original intention was to move exclusively to Nix, but given some of the shortcomings related to how desktop applications are discoverable in MacOS' Spotlight search, the conclusion was to modify the dotfiles to ensure as much compatibility between the two package managers (read #25).
⚠️ Note: The installation will unforgivingly replace all the files in your home directory that match the files in this repo. Back them up if you do not want to lose them.
The install command to use depends on whether the host machine's SSH key has been added to GitHub. If it is a new machine that does not have a key, or this distinction is confusing, go with "No."
| SSH Key on GitHub | Install Command |
|---|---|
| Yes | cd ~ && curl -sL https://raw.githubusercontent.com/danemacmillan/dotfiles/master/bin/__dotfiles_install | bash - |
| No | cd ~ && curl -sL https://raw.githubusercontent.com/danemacmillan/dotfiles/master/bin/__dotfiles_install | bash -s -- nossh |
Just run dotfiles from anywhere. It is in the ${PATH}.
Several arguments can be used with the dotfiles utility:
dotfiles stow: Create all symlinks.dotfiles unstow: Unlinks all symlinks.dotfiles restow: Unlinks and re-links all symlinks. Effective for pruning.dotfiles skippackages: Run command but skip packages installation. This is only recommended once all the packages have been installed at least once.
Check tab completion for all possible arguments.
Local customizations can be made to dotfiles without actually touching the
code. It generates several local config templates at ${XDG_DATA_HOME}/doftiles.
That path usually expands to ${HOME}/.local/shared/dotfiles.
This is the second-to-last file sourced by ${HOME}/.bashrc. Write in any local
configuration and environment changes here.
This is the last file sourced by ${HOME}/.bashrc. This one is even more
specific than the previous one, as it includes the hostname of the machine. This
is useful when sharing environments across machines, and each machine requires
slight changes.
For example, my machine generates a file called macmillanator.local.shell.local.
I have a virtual machine that shares the same ${HOME}, so on that machine,
dotfiles also generates a vagrant.test.shell.local file. Both of these files
co-exist, and do not interfere with each other's respective environments.
Putting all local configuration changes in shell.local would mean both
environments share the same changes, which is not always desired.
This file is included at the bottom of the global git config. It is typically used to store personal credentials.
These are some features or configuration choices worth highlighting.
The XDG Base Directory Specification
is created for operating systems that do not support it by default. This is
done by creating all the $XDG_* environment variables and their corresponding
directories. Strict adherence to the specification has been observed.
Tools that natively support the specification will leverage these environment
variables and directories without additional work. If the variables and
directories were already available, dotfiles will respect them.
Read the source to see how the XDG spec environment variables and directories are created.
A number of tools do not natively support the specification, so in those
instances dotfiles have modified environment variables, aliases, and
configurations so that they can emulate support. These tools will be referred
to as having partial
support.
To see all of the tools adhering to the XDG spec, both with official support
and partial workarounds, look in home/.config
and home/.local/share.
dotfiles is organized into a very deliberate, tidy structure. The effort was
made to ensure a distinction existed between the canonical dotfiles that
comprise all the plain settings and configurations, and the control dotfiles
that typically arise from the need to manage the canonical ones. I never liked
having them mixed together in the {$HOME} directory.
dotfiles
├── /bin -> Essential executable scripts for dotfiles. Available in $PATH.
├── /dpm -> Dotfiles package manager ("dpm"): TODO EXPLAIN
├── /home -> Canonical dotfiles that mirror ${HOME}. Symlink targets.
│ ├── /.config -> ${XDG_CONFIG_HOME}
│ ├── /.local -> ${XDG_DATA_HOME}
│ └── /bin -> Miscellaneous executable scripts. Available in $PATH.
└── /source -> Core scripts sourced by dotfiles.
└──bootstap -> Bootstrap file that connects everything.
These are the files that contain all of the configurations for a new environment, from all variety of tools and utilities. This is what I refer to as canonical dotfiles.
The contents of this directory are what appears in a user's ${HOME} directory.
Note that there are very few files at the root. That means that the ${HOME}
directory itself will also be kept clean, aside from a few culprits that have
not been able to be coerced into adhering to the XDG spec. The contents of this
directory and its subdirectories are symlinked into ${HOME}.
Traditionally, and by most dotfiles' standards, these files are the ones at the
root of a repository, as they are also traditionally at the root of a user's
${HOME} directory. dotfiles tidies things up and places them in their own
directory, in order to serve as a clean reference to what actually symlinks
into ${HOME}. This is achieved because of dotfiles's strict adherence to
the XDG spec. This is the only directory that will have contents symlinked. All
other files are either sourced internally, or available in the ${PATH}.
dotfiles include a package management-like script for handling
dependencies from a wide array of package manager types. This is what enables
it to create environments across a variety of MacOS and GNU/Linux operating
systems. bin/dpm is the tool used for this. It will eventually become its own
repository.
TODO: explain how this works.
As of November 16, 2021, these dotfiles replaced manual symlink creation with
the stow command. Everything under dotfiles/home will be symlinked using
stow.
There is a technique in use for users of iCloud Drive, that will also symlink
any files that are found at:
/Users/${USER}/Library/Mobile Documents/com~apple~CloudDocs/${USER}. This is
useful for any sensitive config files that usually co-exist with config files
that are symlinked from these dotfiles. For example, if a
/Users/${USER}/Library/Mobile Documents/com~apple~CloudDocs/${USER}/.ssh
directory exists, it will be symlinked to ${HOME}/.ssh alongside the
non-sensitive config files that are stored in this repository.