{"id":13572591,"url":"https://github.com/aaronbates/dotfiles","last_synced_at":"2025-04-04T10:30:47.161Z","repository":{"id":218000079,"uuid":"102154905","full_name":"aaronbates/dotfiles","owner":"aaronbates","description":"macOS dotfiles — migrate, backup, config, brew, dev, and a whole lot more.","archived":false,"fork":false,"pushed_at":"2021-05-01T11:40:19.000Z","size":1302,"stargazers_count":87,"open_issues_count":1,"forks_count":8,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-11-05T05:34:28.634Z","etag":null,"topics":["bash","dotfiles","git","mackup","tmux","vim"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronbates.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-01T21:36:21.000Z","updated_at":"2024-10-03T10:09:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"4d59c430-7c10-4184-b570-72172069cf8a","html_url":"https://github.com/aaronbates/dotfiles","commit_stats":null,"previous_names":["aaronbates/dotfiles"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronbates%2Fdotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronbates%2Fdotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronbates%2Fdotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronbates%2Fdotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronbates","download_url":"https://codeload.github.com/aaronbates/dotfiles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247160230,"owners_count":20893795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","dotfiles","git","mackup","tmux","vim"],"created_at":"2024-08-01T14:01:27.760Z","updated_at":"2025-04-04T10:30:47.141Z","avatar_url":"https://github.com/aaronbates.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# `$HOME sweet ~/`\n\nYour dotfiles are how you personalize your system.\n\nThese are mine. Built for Mac OS X. Certified lit :fire: :fire: :fire:\n\n**Rationale**\n\nSetting up a new developer machine can be **ad-hoc**, **manual**, and **time-consuming**. This project simplifies that process using easy-to-understand instructions, configuration and scripts.\n\n\u003e Our goal is to automate at least **80%** of any new macOS system setup.\n\n## What's in the box?\n\nSetup and config for bash, curl, git, node, ruby, tmux, vim, brew, apps, dev environments and more — there's a lot to list so please see the full [Package Contents](docs/package-contents.md).\n\n### Highlights\n\n- **Xcode Command Line Tools** with automated install.\n- **Awesome bash setup**: [aliases](bash/.aliases), [functions](bash/.functions), [z](https://github.com/rupa/z), smart prompt, tab completion and more.\n- **Git done right**: [aliases](git/.gitconfig), [hub](https://hub.github.com), [git-friendly](https://github.com/jamiew/git-friendly) and custom scripts.\n- **Vim for the win** via [vim-pathogen](https://github.com/tpope/vim-pathogen), [vim-sensible](https://github.com/tpope/vim-sensible) and other plugins.\n- **tmux to the max** using [config](tmux/.tmux.conf) and shortcuts.\n- **Homebrew package manager** to install tools, applications and fonts.\n- **Must-have tools**: GNU core utils, gnupg, [quick look plugins](https://github.com/sindresorhus/quick-look-plugins), [wifi-password](https://github.com/rauchg/wifi-password), etc.\n- **Must-have apps**: Caffeine, Dropbox, Chrome, [Spectacle](https://www.spectacleapp.com), Spotify, etc.\n- **Developer tools**:  AWS CLI, Docker, MySQL, Postgres, Python, Yarn, etc.\n- **Developer apps**: iTerm2, Slack, VS Code, etc.\n- **Node development** using [asdf](https://github.com/asdf-vm/asdf) with global package installer.\n- **Ruby development** using [rbenv](https://github.com/rbenv/rbenv) and [ruby-build](https://github.com/rbenv/ruby-build).\n- **Goodies in [bin](bin)** including git and tmux tools.\n\nAlso, last but not least:\n\n- **[Setup scripts](#setup)** to manage backup, install, config and symlinking (plus [migration](#migration)).\n- **Mackup** to [backup and restore](#mackup-for-backup) app settings and personal files.\n- **OS X defaults** geared towards developers.\n\nSounds good? Let's go.\n\n## Install\n\n*Note: If working on a fresh install I recommend reading my [Mac OS X Setup Guide](docs/macos-setup.md) first.*\n\n### Using Git\n\nClone the repository wherever you prefer — I like to store the files in **`~/projects/dotfiles`** and then symlink that to `~/dotfiles` (see [Symlinks](#step-5-symlinks)).\n\n```bash\n$ git clone https://github.com/aaronbates/dotfiles.git    \n```\n\n## Structure\n\nTo keep the project organised all files are split into directories and grouped around topic areas:\n\n- **`ack`** — ack config\n- **`bash`** — bash specific config\n- **`bin`** — various binaries, symlinked to `~/bin` and in `$PATH`\n- **`curl`** — curl config\n- **`editor`** — editor config (including linters)\n- **`git`** — git config, attributes and ignore files\n- **`iterm2`** — iterm2 themes\n- **`mackup`** — config to backup app settings and personal files\n- **`.mackup`** — `.cfg` files for custom apps, symlinked to `~/.mackup`\n- **`macos`** — macOS prefs\n- **`node`** — node config\n- **`ruby`** — ruby config\n- **`screen`** — screen config\n- **`setup`** — install, migrate and backup scripts\n- **`shell`** — general shell config\n- **`terminal`** — terminal themes\n- **`tmux`** — tmux config\n- **`vim`** — vim config\n- **`wget`** — wget config\n- **`/`** — project files and setup script\n\nSee [Extending](#extending) for information on adding new topics.\n\n## Symlinks\n\n[Symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (aka \"symlinks\") allow you to point one location on a system to another, be that a file or directory. They are similar to aliases and shortcuts, but more \"powerful\" in the context we'll be using them.\n\nMost dotfiles need to live in the root of a user's directory (`~/`) for applications to find them.\n\nRather than copy files to `~/` or put my entire `$HOME` under [version control](https://en.wikipedia.org/wiki/Version_control), I prefer to symlink dotfiles to my user directory. This offers several benefits:\n\n1. **I can edit files in one place** — changes apply to both my current system and this project's repo.\n2. **My user directory is clean** — no git repo in `~/`, no mess, no need for a complex `.gitignore`.\n3. **Symlinks are easy** — add, refresh and unlink using a config script.\n\nOK, that's enough theory, let's get things set up.\n\n## Setup\n\n:warning: **Scripts in this project perform automated tasks. Review the code first and use at your own risk!** :warning:\n\nThis projects takes a light-weight approach to automation using a combination of **[Homebrew](https://brew.sh)**, **[Homebrew Cask](https://caskroom.github.io)**, and **shell scripts**.  To setup simply open Terminal then:\n\n```bash\n$ cd ~/projects/dotfiles # or wherever you cloned to.\n$ ./setup.sh\n```\n\nThe setup process will start and guide you through:\n\n![Setup screen](docs/setup.png)\n\nYou'll also be asked to enter your password once at the start — **if using on a fresh install, you'll have to restart after the first run applies system updates.**\n\n### Step-by-step\n\nSetup consists of six steps:\n\n1. [**Backup** directories and files we'll be touching](#step-1-backup)\n2. [Create required **directories**](#step-2-directories)\n3. [Install **Xcode Command Line Tools**](#step-3-xcode-command-line-tools)\n4. [Install **Homebrew** and all required apps](#step-4-homebrew)\n5. [Create **symlinks** for directories and files](#step-5-symlinks)\n6. [Final touches](#step-6-final-touches)\n\n### Step 1: Backup\n\n\u003e This step runs the [`setup/backup.sh`](setup/backup.sh) script.\n\nCreates `~/backup/dotfiles-backup` then takes a copy of all files on the current system which would be replaced by the setup script (as defined [here](docs/backup.md)) — it also backs up some other useful local directories and files.\n\n### Step 2: Directories\n\n\u003e This step runs the [`setup/directories.sh`](setup/directories.sh) script.\n\nCreates required and preferred directories (if they don't already exist) for example: `~/Applications`, `~/projects`, `~/code`, `.ssh/control`, etc.\n\n### Step 3: Xcode Command Line Tools\n\n\u003e This step runs the [`setup/xcodecli.sh`](setup/xcodecli.sh) script.\n\nThe [Xcode Command Line Tools](https://developer.apple.com/library/content/technotes/tn2339/_index.html) contain tools required by this setup script, this step will:\n\n1. Install the Xcode Command Line Tools\n2. Configure the tools\n3. Prompt for license agreement\n\n### Step 4: Homebrew\n\n\u003e This step runs the [`setup/brew.sh`](setup/brew.sh) script.\n\nPackage managers make it easy to install, update and remove software The best package manager for OS X is [Homebrew](http://brew.sh) — this step installs Homebrew along with many useful formulae and apps:\n\n1. Install Homebrew\n2. Install [Core utils](docs/package-contents.md#core-utils)\n3. Install [Other useful utils](docs/package-contents.md#other-useful-utils)\n4. Install [Backup tools](docs/package-contents.md#backup-tools)\n5. Install [Development tools](docs/package-contents.md#development-tools)\n6. Install [Databases](docs/package-contents.md#databases)\n7. Install [DevOps tools](docs/package-contents.md#devops-tools)\n8. Install [Webfont tools](docs/package-contents.md#webfont-tools)\n9. Install [Fonts](docs/package-contents.md#fonts)\n10. Install [Applications](docs/package-contents.md#applications-installed-via-homebrew-cask)\n11. Install [Quicklook plugins](docs/package-contents.md#quicklook-plugins)\n\nThe script then uses [`mas`](https://github.com/mas-cli/mas) to install some [Mac App Store applications](docs/package-contents.md#mac-app-store-applications) unavailable via Homebrew.\n\n#### Node setup\n\nPost application install the script [`setup/node.sh`](setup/node.sh) is run which:\n\n1. Installs the latest Node release using [`asdf`](https://github.com/asdf-vm/asdf)\n2. Installs the current LTS Node release using [`asdf`](https://github.com/asdf-vm/asdf)\n3. Updates `npm`\n4. Creates `~/.node-global-modules`\n5. Installs [global modules](docs/package-contents.md#global-modules) to this folder\n\n#### Vim setup\n\nAfter this, the script [`setup/vim.sh`](setup/vim.sh) is run which:\n\n1. Creates required vim directories\n2. Installs [vim-pathogen](https://github.com/tpope/vim-pathogen)\n3. Installs [plugins](docs/package-contents.md#vim)\n\n### Step 5: Symlinks\n\n\u003e This step runs the [`setup/symlinks.sh`](setup/symlinks.sh) script.\n\nCreates symlinks for all required directories and files to `~/`. These are defined in [`setup/files.sh`](setup/files.sh) as:\n\n1. All directories declared in `$dotfilesdirarray`\n2. Any file of an [accepted type](#which-files-will-be-symlinked) in a directory declared in `$dotfilesfilearray`\n3. Custom manually declared files ([git-friendly](https://github.com/jamiew/git-friendly) scripts to `bin`)\n\nThis also links the local repository directory to `~/dotfiles` if it was cloned to a different location.\n\n**Symlinking directories:** If directory `bin` is declared in `$dotfilesdirarray` then the whole directory will be symlinked to `~/bin`.\n\n**Symlinking files:** If directory `bash` is declared in `$dotfilesfilearray` then any file of an [accepted type](#which-files-will-be-symlinked) will be symlinked to `~/`. For example:\n\n- `bash/.aliases` links to `~/.aliases`\n- `bash/.bash_profile` links to `~/.bash_profile`\n- `bash/.functions` links to `~/.function`\n- and so on.\n\n#### Which files will be symlinked?\n\n**Only files of type `.*`, `*.cfg` and `*.conf` will be symlinked.** Also, certain files are explicitly ignored:\n\n- `.DS_Store`, `.git`, `.osx` and `.macos`\n- any file of type `*.sh`\n\n#### Symlink scripts\n\nThe symlink script can be run independently from a shell — it performs various checks, asks questions and provides feedback. Equally there is an [`setup/unlink.sh`](setup/unlink.sh) which unlinks all created symlinks.\n\n### Step 6: Final touches\n\nFinally a number of other tasks are performed:\n\n- Install a [better .nanorc config](https://github.com/scopatz/nanorc)\n- Set `chmod 700 ~/.ssh` and `chmod 600 ~/.ssh/*` (see [here](https://mediatemple.net/community/products/dv/204644740/using-ssh-keys-on-your-server))\n- *Note: see [here](docs/getting-started.md#a-word-on-unix-style-permissions) for more info on Unix style permissions*\n- Install Solarized Dark Theme for Terminal\n- Install Solarized Dark High Contrast Theme for iTerm2\n\n:zap: **Congrats, you now have an awesome macOS setup.** Open up iTerm2 and explore. :clap:\n\n## Usage\n\nIt's beyond the scope of this readme to fully document all features, but you can find some tips and features of notes in the [Getting Started](docs/getting-started.md) guide.\n\n## Customise using \"local config\"\n\nThis project can be easily customised to suit personal settings and local requirements using \"local config\" files. This allows you to:\n\n- Use custom settings without forking this project.\n- Set config you don’t want to commit to a public repo.\n- Store credentials that should remain private.\n\nAs mentioned, it's **very** important to avoid storing private data or credentials in a dotfiles repository, using \"local config\" files that are never committed to public version control is a good way to achieve this.\n\n### Adding custom bash commands\n\nIf an `~/.extra` file exists, it will be sourced on load after all other bash files. You can use this to store custom aliases, functions, exports and settings.\n\n**Example `~/.extra` file:**\n\n```bash\nalias myalias=some-other-command -options\n\nmy_function () {\n  do something here\n}\n\nexport MY_SETTING=VALUE\n```\n\nYou could also use `~/.extra` to override *existing* settings, functions and aliases — but at that point, it's probably better just to [fork](#fork) and create your own dotfiles. :raised_hands:\n\n### Customising your `$PATH`\n\nThe included [`.path`](bash/.path) file is pre-configured and sourced on load. To add custom entries to your path, create a `~/.path.local` file.\n\n**Example `~/.path.local` file:**\n\n```bash\n# Add to the start of the path\nPATH=\"/your/path/here:$PATH\"\n\n# Add to the end of the path\nPATH=\"$PATH:/your/path/here\"\n```\n\nThis will also be sourced on load and the final `$PATH` will be deduplicated on export.\n\n### Customising Git\n\nCustomise your Git config by creating a `~/.gitconfig.local` file which will extend [`.gitconfig`](git/.gitconfig). Use this to store private details such as your user credentials and signing key.\n\n**Example `~/.gitconfig.local` file:**\n\n```ini\n[user]\n\n  name = \"Firstname Lastname\"\n  email = \"your@emailaddress.com\"\n\n[github]\n\n  user = your-github-username\n\n[credential]\n\n  helper = osxkeychain\n\n[commit]\n\n  signingkey = YOUR-SIGNING-KEY-HERE\n```\n\n### Customising Vim\n\nCustomise your Vim config by creating a `~/.vimrc.local` file which will extend [`.vimrc`](vim/.vimrc).\n\n### Customising tmux\n\nCustomise your tmux config by creating a `~/.tmux.conf.local` file which will extend [`.tmux.conf`](tmux/.tmux.conf).\n\n## Fork\n\n**Feel free to fork this repo, hack around, and make it your own** :ok_hand:\n\n### Extending\n\nThis project is organised around topics, see [Structure](#structure) for more information.\n\nTo add a new topic to your forked dotfiles, you can simply add a `/topic-name` directory and put any files in there. Let's use \"Java\" as an example:\n\n1. Create a `java` directory in your dotfiles root.\n2. Inside there, create two files: `java.conf` and `.javarc`\n\nIf you then edit [`setup/files.sh`](setup/files.sh) you have two options:\n\n#### A) Symlink the entire folder\n\nThis will symlink the `java` directory to `~/java` (if that doesn't already exist). Useful if you want access to a number and variety of files within a directory.\n\nTo do this, simply add `\"$dotfilesdir/java\"` to the `dotfilesdirarray`:\n\n```bash\n# Declare array of directories we want to symlink.\ndeclare -a dotfilesdirarray=(\n  \"$dotfilesdir/bin\"\n  ...  \n  \"$dotfilesdir/java\"\n)\n```\n\nThen run the [symlink script](#symlink-scripts) to apply the link.\n\n#### B) Symlink *files* in the folder\n\nThis will symlink files of [accepted types](#which-files-will-be-symlinked) in the `java` directory to `~/` (if they don't exist already) — so for our example, it would create links to `~/java.conf` and `~/.javarc`.\n\nTo do this, add `\"$dotfilesdir/java\"` to the `dotfilesfilearray`:\n\n```bash\n# Declare array of directories we want to symlink files from.\ndeclare -a dotfilesfilearray=(\n  \"$dotfilesdir/bash\"\n  \"$dotfilesdir/git\"\n  ...\n  \"$dotfilesdir/java\"\n)\n```\n\nThen run the [symlink script](#symlink-scripts) to apply the links.\n\n## Going further\n\n### Sensible Mac OS X defaults\n\nWhen setting up a new Mac, you may want to set some sensible defaults (as maintained by [Mathias](http://mths.be/macos)).\n\nI have included my tweaked version of these settings in this repository, [take a look](macos/.macos) but :warning: **be very careful using this file** :warning: — I do *not* recommend just running it without reviewing and understanding it carefully first.\n\n```bash\n$ cd ~/dotfiles/macos \u0026\u0026 ./.macos\n```\n\n*If in any doubt, don't run this script, rather configure what you can manually.*\n\n### Mackup for backup\n\n[Mackup](https://github.com/lra/mackup) is a fantastic tool that allows you to: backup personal application settings and private data; sync that data between computers; and then easily restore your configuration to a fresh install — all in a simple command line interface. Seems good!\n\nWhile by no means a comprehensive backup solution, Mackup keeps things simple, currently supports [over 360 applications](https://github.com/lra/mackup/mackup/applications) and can store data on Dropbox, Google Drive, iCloud or any path you can copy to.\n\n#### How I use Mackup\n\nI store on Dropbox and explicitly declare which apps to sync and which to ignore — anything handled by my dotfiles is ignored (bash, git, vim etc.)\n\nI backup a wide range of other applications including those containing credentials such as aws, gnupg and ssh. I also backup apps not natively supported using custom `.cfg` files. For example, to backup [Ulysses](https://ulyssesapp.com) (an amazing markdown writing app) I created a `~/.mackup` directory and placed a `ulysses.cfg` file inside:\n\n```ini\n[application]\nname = Ulysses\n\n[configuration_files]\nLibrary/Preferences/com.soulmen.ulysses3.plist\nLibrary/Preferences/com.ulyssesapp.mac.plist\n```\n\nIt is usually straight-forward to find which `.plist` files in `Library/Preferences` you'll need to list, they always feature the application name.\n\nTaking that a step further we can also declare a \"personal files\" application using a `personal-files.cfg` and then cherry pick any other files we want to backup while keeping them out of a public repo:\n\n```ini\n[application]\nname = Personal Files\n\n[configuration_files]\n.gitconfig.local\n.extra\n```\n\nWhen I declare this in my main [`.mackup.cfg`](mackup/.mackup.cfg) they are handled with ease:\n\n```ini\n[storage]\nengine = dropbox\ndirectory = mackup\n\n# Apps to sync — if empty, syncs all supported.\n# custom: personal-files, break, grammarly, iconjar, iterm2, oversight, ulysses\n[applications_to_sync]\npersonal-files\naws\n...\nulysses\n```\n\nA simple `$ mackup backup` saves everything to Dropbox and I can later `$ mackup restore` on a fresh install to get these settings back (you can also easily `$ mackup uninstall`).\n\nThese dotfiles symlink my Mackup config into `~/` — take a look :eyes:.\n\n### Migration\n\nIn addition to setup, it's possible to use these dotfiles on an configured Mac system to migrate to a new machine using the [`setup/migrate.sh`](setup/migrate.sh) script.\n\n:warning: Caution is advised here — see the [Migration Guide](docs/migration.md) for more information.\n\n## Acknowledgements\n\nCredit, inspiration and thanks to:\n\n- [Dev Setup](https://github.com/donnemartin/dev-setup)\n- [Awesome Dotfiles](https://github.com/webpro/awesome-dotfiles)\n- [Mathias](https://github.com/mathiasbynens/dotfiles)\n- [Paul Irish](https://github.com/paulirish/dotfiles)\n- [Holman](https://github.com/holman/dotfiles)\n- [Mislav](https://github.com/mislav/dotfiles)\n- [Springload](https://github.com/springload/dotfiles)\n\nAnd too many others to name.\n\n## License\n\n[MIT](https://github.com/aaronbates/dotfiles/blob/master/LICENSE-MIT.txt) \u0026copy; 2017 Aaron Bates ([http://aaronbates.me](http://aaronbates.me))\n\n## TODO\n\n- [ ] Install without Git\n- [ ] Take user info for custom config setup (name/email/url)\n- [ ] Add BATS test suite\n- [ ] Ruby config\n- [ ] Databases config\n- [ ] Devops config (VM, Docker)\n- [ ] Consider additional [vim plugins](https://github.com/square/maximum-awesome)\n\n----\n\n:octocat: There's no place like `$HOME`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronbates%2Fdotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronbates%2Fdotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronbates%2Fdotfiles/lists"}