Skip to content

✨ Features#

Installation and setup of the dotfiles project is the use of an opinionated set of tools and configurations. These configurations are based on my personal preferences and are designed to be sensible defaults for most users.

This project functions by symbolically linking the configuration files and directories in this repository to their appropriate locations on your system. Some tools and frameworks require that you clone the repository locally, this project uses git submodules to manage these dependencies.

Shell Configuration#

Zsh#

the Z shell (zsh) is set up with a number of frameworks and plugins to make your terminal experience more productive and enjoyable:

Aliases#

  • c - clear the terminal
  • ll - list files in long format

Functions#

Dotfiles Management#

The dotfiles command is a wrapper around the dotfiles project and provides a number of useful operations:

Usage:
  dotfiles <target>

dotfiles 🚀
  bootstrap            Initialize the project by running the bootstrap script.
  deps                 Install dependencies for the project based on the OS.
  sync                 Update the project and its submodules.

macOS 🍏
  brew-bundle          Install packages from the Brewfile.
  brew-cleanup         Cleanup Homebrew, remove unused packages (dry-run).
  brew-cleanup-force   Cleanup Homebrew, remove unused packages.
  xbrew-bundle         Install x86 packages from the XBrewfile.
  xbrew-cleanup        Cleanup x86 Homebrew, remove unused packages (dry-run).
  xbrew-cleanup-force  Cleanup x86 Homebrew, remove unused packages.

python 🐍
  pyenv-install-all    Install all python versions into pyenv.
  pyenv-compile        Compile pyenv bash extension to optimize performance.
  pipx-install-all     Install Python CLI packages from PipFile
  uv-install           Install uv Python manager.

nvim 🌌
  nvim-build           Build Neovim from source.

rust 🦀
  rust-install         Install Rust and its components.

general 🌐
  version              Show the version of the project.
  help                 Show this help message and exit.

Directory Operations#

  • mkcd: Create a directory and change to it.
  • mktmpdir: Create a temporary directory.
  • mkcdtmp: Create a temporary directory and change to it.
  • ideacd: Open a directory in the IDE and switch to it.
  • runin: Run command in another directory and return.

Git Operations#

  • check: Checkout a branch.
  • git-remove-deleted: Remove branches that have been deleted.
  • git-tree: Display a tree considering .gitignore.

Search Operations#

  • f: Find a file by name.
  • r: Grep recursively.

Miscellaneous Tasks#

  • is_command: Check if a command exists.
  • date_iso8601: Generate an ISO8601 formatted date string.
  • hash_sha256: Generate a SHA-256 hash of a file, string, or stdin.
  • untar: Unpack a tarball or zip file.

AWS Operations#

  • aws-docker-login: Login to AWS ECR.

Logging#

  • log_event: Log an event with a timestamp and a message. Supports different levels such as info, error, warning, debug, and critical.

Executables#

  • aptfile: Install packages from a file using apt-get
  • has: Check if a program exists, and its version
  • now: Get the current date and time
  • pacapt: Universal package manager wrapper
  • pipx-utils: Additional utilities for pipx
  • xbrew - x86 homebrew (macOS only)

Python#

  • pyenv for managing Python versions
  • pipx for installing Python CLI tools

hatch#

  • Sensible defaults for hatch
📄 hatch/config.toml 
[dirs.env]
virtual = ".venv"
pip-compile = ".venv"

git#

  • Reasonable settings at ~/.gitconfig
  • Reasonable global gitignore at ~/.gitignore
  • gh (GitHub CLI) for git auth and GitHub interactions
📄 .gitconfig 
[user]
    name = Justin Flannery
    email = [email protected]
[init]
    defaultBranch = main
[pull]
    rebase = false
[push]
    autoSetupRemote = true
[core]
    excludesfile = ~/.gitignore
[alias]
    dunk = !git add --all --intent-to-add && git diff HEAD | dunk | less -R --mouse --wheel-lines=3
[filter "lfs"]
    smudge = git-lfs smudge -- %f
    process = git-lfs filter-process
    required = true
    clean = git-lfs clean -- %f
[credential "https://github.com"]
    helper =
    helper = !gh auth git-credential
[credential "https://gist.github.com"]
    helper =
    helper = !gh auth git-credential
📄 .gitignore 
#################################################################################
# https://github.com/github/gitignore/blob/main/Global/macOS.gitignore
#################################################################################

# General
.DS_Store
.AppleDouble
.LSOverride

# Icon must end with two \r
Icon

# Thumbnails
._*

# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk

#################################################################################
# https://github.com/github/gitignore/blob/main/Global/Linux.gitignore
#################################################################################

*~

# temporary files which can be created if a process still has a handle open of a deleted file
.fuse_hidden*

# KDE directory preferences
.directory

# Linux trash folder which might appear on any partition or disk
.Trash-*

# .nfs files are created when an open file is removed but is still being accessed
.nfs*

#################################################################################
# https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
#################################################################################

# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

# Non-default ignores
.idea/*.iml
.idea/*.xml
.idea/.gitignore

# User-specific stuff
.idea/**/workspace.xml
.idea/**/tasks.xml
.idea/**/usage.statistics.xml
.idea/**/dictionaries
.idea/**/shelf

# AWS User-specific
.idea/**/aws.xml

# Generated files
.idea/**/contentModel.xml

# Sensitive or high-churn files
.idea/**/dataSources/
.idea/**/dataSources.ids
.idea/**/dataSources.local.xml
.idea/**/sqlDataSources.xml
.idea/**/dynamic.xml
.idea/**/uiDesigner.xml
.idea/**/dbnavigator.xml

# Gradle
.idea/**/gradle.xml
.idea/**/libraries

# Gradle and Maven with auto-import
# When using Gradle or Maven with auto-import, you should exclude module files,
# since they will be recreated, and may cause churn.  Uncomment if using
# auto-import.
# .idea/artifacts
# .idea/compiler.xml
# .idea/jarRepositories.xml
# .idea/modules.xml
# .idea/*.iml
# .idea/modules
# *.iml
# *.ipr

# CMake
cmake-build-*/

# Mongo Explorer plugin
.idea/**/mongoSettings.xml

# File-based project format
*.iws

# IntelliJ
out/

# mpeltonen/sbt-idea plugin
.idea_modules/

# JIRA plugin
atlassian-ide-plugin.xml

# Cursive Clojure plugin
.idea/replstate.xml

# SonarLint plugin
.idea/sonarlint/

# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
crashlytics-build.properties
fabric.properties

# Editor-based Rest Client
.idea/httpRequests

# Android studio 3.1+ serialized cache file
.idea/caches/build_file_checksums.ser

#################################################################################
# https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
#################################################################################

.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets

# Local History for Visual Studio Code
.history/

# Built Visual Studio Code Extensions
*.vsix

#################################################################################
# https://github.com/github/gitignore/blob/main/Python.gitignore
#################################################################################

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
# lib/ # Javascript Projects
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
#   For a library or package, you might want to ignore these files since the code is
#   intended to run in multiple environments; otherwise, check them in:
# .python-version

# pipenv
#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
#   However, in case of collaboration, if having platform-specific dependencies or dependencies
#   having no cross-platform support, pipenv may install dependencies that don't work, or not
#   install all needed dependencies.
#Pipfile.lock

# poetry
#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
#   This is especially recommended for binary packages to ensure reproducibility, and is more
#   commonly ignored for libraries.
#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock

# pdm
#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
#   in version control.
#   https://pdm.fming.dev/#use-with-ide
.pdm.toml

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

Neovim#

Neovim is a highly configurable, Vim-based text editor. The configuration of Neovim is managed by the dotfiles project and is configured with the nvim-lua/kickstart.nvim project template.

Neovim on Linux

Not all linux distributions have the latest version of Neovim available in their package managers. If this is the case, it is recommended to build Neovim from source to get the latest version. The dotfiles project has exposed a simple command to do this for you:

dotfiles nvim-build

Building Neovim from source requires a number of dependencies, which can be installed manually:

apt-get install ninja-build gettext cmake unzip curl build-essential

yum install gcc gcc-c++
yum install neovim

Applications and Tools#

  • awsume is an AWS role management tool configured with dotfiles. See the awsume docs in dev-setup for more information.

macOS#

A good number of macOS-specific applications are installed via Homebrew, they're enumerated in the macos/Brewfile which is documented in the dependencies section.

Linux#

Similarly, a good number of Linux-specific applications are installed via Apt, they're enumerated in the linux/Aptfile which is documented in the dependencies section.