{"id":13395092,"url":"https://github.com/nicknisi/dotfiles","last_synced_at":"2025-05-14T00:10:54.571Z","repository":{"id":2985171,"uuid":"4001241","full_name":"nicknisi/dotfiles","owner":"nicknisi","description":"vim, zsh, git, homebrew, neovim - my whole world","archived":false,"fork":false,"pushed_at":"2025-04-06T22:29:20.000Z","size":43773,"stargazers_count":2817,"open_issues_count":1,"forks_count":365,"subscribers_count":82,"default_branch":"main","last_synced_at":"2025-04-07T05:02:26.274Z","etag":null,"topics":["dotfiles","git","homebrew","neovim","neovim-setup","osx","shell","tmux","tmux-configuration","vim","zsh","zsh-setup"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"7420dev/android_hardware_samsung","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicknisi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2012-04-12T04:21:16.000Z","updated_at":"2025-04-06T22:29:25.000Z","dependencies_parsed_at":"2024-05-30T08:04:52.250Z","dependency_job_id":"d10305b8-1684-440e-b7dc-e4faee07462a","html_url":"https://github.com/nicknisi/dotfiles","commit_stats":{"total_commits":1534,"total_committers":21,"mean_commits":73.04761904761905,"dds":0.01564537157757495,"last_synced_commit":"32404308877ad6aa243a81d5bde9d68607c25acb"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicknisi%2Fdotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicknisi%2Fdotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicknisi%2Fdotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicknisi%2Fdotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicknisi","download_url":"https://codeload.github.com/nicknisi/dotfiles/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248201576,"owners_count":21064149,"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":["dotfiles","git","homebrew","neovim","neovim-setup","osx","shell","tmux","tmux-configuration","vim","zsh","zsh-setup"],"created_at":"2024-07-30T17:01:41.800Z","updated_at":"2025-04-10T10:46:51.779Z","avatar_url":"https://github.com/nicknisi.png","language":"Lua","funding_links":[],"categories":["Lua","Vim script","Shell","GLSL","Credits","zsh","vim","HarmonyOS"],"sub_categories":["Basic usage","Windows Manager"],"readme":"# Dotfiles\n\nWelcome to my world! Here you'll find a collection of configuration files for various tools and programs that I use on a daily basis. These dotfiles have been carefully curated and customized to streamline **my** workflow and improve **my** productivity. Your results may vary, but feel free to give it a try! Whether you're a fellow developer looking to optimize your setup or just curious about how I organize my digital life, I hope you find something useful in these dotfiles. So take a look around and feel free to borrow, modify, or fork to your heart's content. Happy coding!\n\n\u003e [!Note]\n\u003e\n\u003e Did you arrive here through my YouTube talk, [vim + tmux](https://www.youtube.com/watch?v=5r6yzFEXajQ)? My dotfiles have changed tremendously since then, but feel free to peruse the state of this repo [at the time the video was recorded](https://github.com/nicknisi/dotfiles/tree/aa72bed5c4ecec540a31192581294818b69b93e2).\n\n\u003cimg width=\"1600\" alt=\"capture-20231114134612\" src=\"https://github.com/nicknisi/dotfiles/assets/293805/43dff50a-8fad-44e5-b979-d72ebd0366f8\"\u003e\n\n## Initial Setup\n\nThe first thing you need to do is to clone this repo into a location of your choosing. For example, if you have a `~/Developer` directory where you clone all of your git repos, that's a good choice for this one, too. This repo is setup to not rely on the location of the dotfiles, so you can place it anywhere.\n\n\u003e [!Note]\n\u003e\n\u003e If you're on macOS, you'll also need to install the XCode CLI tools before continuing.\n\n```bash\nxcode-select --install\n```\n\n```bash\ngit clone git@github.com:nicknisi/dotfiles.git\n```\n\n\u003e [!Note]\n\u003e\n\u003e This dotfiles configuration is set up in such a way that it _shouldn't_ matter where the repo exists on your system.\n\n## The `dot` Command\n\nThis repository includes a powerful `dot` command for managing your dotfiles. It replaces the previous `install.sh` script with a more flexible and maintainable solution.\n\n### Configuration\n\nThe tool respects these environment variables:\n- `DOTFILES`: Path to your dotfiles directory\n- `PATH`: For discovering external commands\n\nBy default, the following directories are ignored when linking:\n- bin\n- applescripts\n- resources\n\n### Basic Usage\n\n```bash\ndot help                    # Show help message and available commands\ndot backup                  # Backup existing dotfiles\ndot link [package]          # Link all or specific package\ndot unlink [package]        # Unlink all or specific package\n```\n\n\u003e[!important]\n\u003e\n\u003eThis command won't be in the path until ZSH is properly configured.\n\u003e Until that's the case, you can run the command from the dotfiles root.\n\u003e ```bash\n\u003e bin/dot \u003ccommand\u003e \u003csubcommand\u003e\n\u003e```\n```\n\n### Backup Options\n\nThe backup command creates a backup of your existing dotfiles before installing new ones:\n\n```bash\ndot backup -d \u003cdirectory\u003e   # Specify backup directory (default: ~/dotfiles-backup)\ndot backup -v               # Verbose output\n```\n\nThis will back up important files and directories including:\n- Existing dotfiles in your home directory\n- Neovim configuration (`~/.config/nvim/`)\n- Vim configuration (`~/.vim/` and `~/.vimrc`)\n\n### Link/Unlink Options\n\n```bash\ndot link -v                # Verbose output\ndot link -t \u003ctarget\u003e       # Specify target directory\ndot link \u003cpackage\u003e         # Link specific package\ndot link all               # Link all packages\n```\n\n### Built-in Commands\n\n#### Git Configuration (`dot git`)\n\n```bash\ndot git setup    # Configure git user settings interactively\n```\n\nSets up personalized Git configuration including name, email, and Github username. The configuration is saved to `~/.gitconfig-local`.\n\n#### macOS Settings (`dot macos`)\n\n```bash\ndot macos defaults    # Configure recommended macOS system defaults\n```\n\nConfigures various macOS system settings including:\n- Finder: show all filename extensions\n- Show hidden files by default\n- Only use UTF-8 in Terminal.app\n- Expand save dialog by default\n- Enable full keyboard access for all controls\n- Enable subpixel font rendering on non-Apple LCDs\n- Use current directory as default search scope in Finder\n- Show Path bar and Status bar in Finder\n- Optimize keyboard settings for development\n\n#### Shell Configuration (`dot shell`)\n\n```bash\ndot shell change     # Change default shell to zsh\ndot shell terminfo   # Install terminal information files\n```\n\nThese commands may not always be reqired. For example, macOS now sets the default shell to ZSH. And, the terminfo is only requried if you're interested in having italic support in Neovim.\n\n#### Homebrew Management (`dot homebrew`)\n\n```bash\ndot homebrew install    # Install Homebrew package manager\ndot homebrew bundle     # Install packages from Brewfile\n```\n\nUsing this command is only needed if your machine does not currently have Homebrew installed. You can also install if the main way by following the [instructions on their website](https://brew.sh).\n\n#### Legacy Cleanup (`dot legacy`)\n\n```bash\ndot legacy clean    # Clean up broken legacy symlinks\n```\n\nThis legacy command specifically cleans up the old symlinks that might exist from rpevious iterations of this repository.\n\n### Extending with Custom Commands\n\nThe `dot` command is extensible. You can add custom commands by:\n\n1. Creating executable scripts named `dot-\u003ccommand\u003e` in your `$PATH`\n2. Adding a \"Description:\" comment for help text\n3. The command will then be available as `dot \u003ccommand\u003e`\n\n## ZSH Configuration\n\nThe prompt for ZSH is configured in the `cnofig/zsh/zshrc` file and performs the\nfollowing operations.\n\n- Sets `EDITOR` to `nvim`\n- Loads any `~/.terminfo` setup\n- Sets `CODE_DIR` to `~/Developer`. This can be changed to the location you use\n  to put your git checkouts, and enables fast `cd`-ing into it via the `c`\n  command\n- Recursively searches the `$DOTFILES/zsh` directory for any `.zsh` files and\n  sources them\n- Sources a `~/.localrc`, if available for configuration that is\n  machine-specific and/or should not ever be checked into git\n- Adds `~/bin` and `$DOTFILES/bin` to the `PATH`\n\n### ZSH plugins\n\nThere are a number of plugins in use for ZSH, and they are installed and\nmaintained separately via the `zfetch` command. `zfetch` is a custom plugin\nmanager available [here](./zsh/functions/zfetch). The plugins that are used are\nlisted in the `.zshrc` and include\n\n- [zsh-async](https://github.com/mafredri/zsh-async)\n- [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting)\n- [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions)\n- [zsh-npm-scripts-autocomplete](https://github.com/grigorii-zander/zsh-npm-scripts-autocomplete)\n- [fzf-tab](https://github.com/Aloxaf/fzf-tab)\n\nAdditional plugins can be added to the `~/.zshrc`, or to `~/.localrc` if you\nwant them to stay out of git.\n\n```bash\n# Add a line like this and the plugin will automatically be downloaded and sourced\nzfetch nicknisi/work-scripts\n```\n\n### Prompt\n\nAloxaf/fzf-tab The prompt is meant to be simple while still providing a lot of\ninformation to the user, particularly about the status of the git project, if\nthe PWD is a git project. This prompt sets `precmd`, `PROMPT` and `RPROMPT`. The\n`precmd` shows the current working directory in it and the `RPROMPT` shows the\ngit and suspended jobs info. The main symbol used on the actual prompt line is\n`❯`.\n\nThe prompt attempts to speed up certain information lookups by allowing for the\nprompt itself to be asynchronously rewritten as data comes in. This prevents the\nprompt from feeling sluggish when, for example, the user is in a large git repo\nand the git prompt commands take a considerable amount of time.\n\nIt does this by writing the actual text that will be displayed int he prompt to\na temp file, which is then used to update the prompt information when a signal\nis trapped.\n\n#### Git Prompt\n\nThe git info shown on the `RPROMPT` displays the current branch name, along with\nthe following symbols.\n\n- `+` - New files were added\n- `!` - Existing files were modified\n- `?` - Untracked files exist that are not ignored\n- `»` - Current changes include file renaming\n- `✘` - An existing tracked file has been deleted\n- `$` - There are currently stashed files\n- `=` - There are unmerged files\n- `⇡` - Branch is ahead of the remote (indicating a push is needed)\n- `⇣` - Branch is behind the remote (indicating a pull is needed)\n- `⇕` - The branches have diverged (indicating history has changed and maybe a\n  force-push is needed)\n- `✔` - The current working directory is clean\n\n#### Jobs Prompt\n\nThe prompt will also display a `✱` character in the `RPROMPT` indicating that\nthere is a suspended job that exists in the background. This is helpful in\nkeeping track of putting vim in the background by pressing CTRL-Z.\n\n#### Node Prompt\n\nIf a `package.json` file or a `node_modules` directory exists in the current\nworking directory, display the node symbol, along with the current version of\nNode. This is useful information when switching between projects that depend on\ndifferent versions of Node.\n\n## Neovim setup\n\n\u003e [!Note]\n\u003e\n\u003e This is no longer a vim setup. The configuration has been moved to be\n\u003e Neovim-specific and (mostly) written in [Lua](https://www.lua.org/). `vim` is\n\u003e also set up as an alias to `nvim` to help with muscle memory.\n\nThe simplest way to install Neovim is to install it from homebrew.\n\n```bash\nbrew install neovim\n```\n\nHowever, it was likely installed already if you ran the `dot homebrew bundle`\ncommand provided in the dotfiles.\n\nAll of the configuration for Neovim starts at `nvim/.config/nvim/init.lua`, which is\nsymlinked into the `~/.config/nvim` directory.\n\n\u003e [!Warning]\n\u003e\n\u003e The first time you run `nvim` with this configuration, it will likely have a\n\u003e lot of errors. This is because it is dependent on a number of plugins being\n\u003e installed.\n\n### Installing plugins\n\nOn the first run, all required plugins should automaticaly by installed by\n[lazy.nvim](https://github.com/folke/lazy.nvim), a plugin manager for neovim.\n\nAll plugins are listed in [plugins.lua](./config/nvim/lua/plugins.lua). When a\nplugin is added, it will automatically be installed by lazy.nvim. To interface\nwith lazy.nvim, simply run `:Lazy` from within vim.\n\n\u003e [!Note]\n\u003e\n\u003e Plugins can be synced in a headless way from the command line using the `vimu`\n\u003e alias.\n\n## tmux configuration\n\nI prefer to run everything inside of [tmux](https://github.com/tmux/tmux). I\ntypically use a large pane on the top for neovim and then multiple panes along\nthe bottom or right side for various commands I may need to run. There are no\npre-configured layouts in this repository, as I tend to create them on-the-fly\nand as needed.\n\nThis repo ships with a `tm` command which provides a list of active session, or\nprovides prompts to create a new one.\n\n```bash\n\u003e tm\nAvailable sessions\n------------------\n\n1) New Session\nPlease choose your session: 1\nEnter new session name: open-source\n```\n\nThis configuration provides a bit of style to the tmux bar, along with some\nadditional data such as the currently playing song (from Apple Music or\nSpotify), the system name, the session name, and the current time.\n\n\u003e [!Note]\n\u003e\n\u003e It also changes the prefix from `⌃-b` to `⌃-a` (⌃ is the _control_ key). This\n\u003e is because I tend to remap the Caps Lock button to Control, and then having\n\u003e the prefix makes more sense.\n\n### tmux key commands\n\nPressing the Prefix followed by the following will have the following actions in\ntmux.\n\n| Command     | Description                    |\n| ----------- | ------------------------------ |\n| `h`         | Select the pane to the left    |\n| `j`         | Select the pane to the bottom  |\n| `k`         | Select the pane to the top     |\n| `l`         | Select the pane to the right   |\n| `⇧-H`       | Enlarge the pane to the left   |\n| `⇧-J`       | Enlarge the pane to the bottom |\n| `⇧-K`       | Enlarge the pane to the top    |\n| `⇧-L`       | Enlarge the pane to the right  |\n| `-` (dash)  | Create a vertical split        |\n| `\\|` (pipe) | Create a horizontal split      |\n\n### Minimal tmux UI\n\nSetting a `$TMUX_MINIMAL` environment variable will do some extra work to hide\nthe tmux status bar when there is only a single tmux window open. This is not\nthe default in this repo because it can be confusing, but it is my preferred way\nto work. To set this, you can use the `~/.localrc` file to set it in the\nfollowing way.\n\n```shell\nexport TMUX_MINIMAL=1\n```\n\n## Docker Setup\n\nA Dockerfile exists in the repository as a testing ground for linux support. To\nset up the image, make sure you have Docker installed and then run the following\ncommand.\n\n```bash\ndocker build -t dotfiles --force-rm --build-arg PRIVATE_KEY=\"$(cat ~/.ssh/id_rsa)\" --build-arg PUBLIC_KEY=\"$(cat ~/.ssh/id_rsa.pub)\" .\n```\n\nThis should create a `dotfiles` image which will set up the base environment\nwith the dotfiles repo cloned. To run, execute the following command.\n\n```bash\ndocker run -it --rm dotfiles\n```\n\nThis will open a bash shell in the container which can then be used to manually\ntest the dotfiles installation process with linux.\n\n## Preferred software\n\nI almost exclusively work on macOS, so this list will be specific to that\noperating system, but several of these reccomendations are also available,\ncross-platform. For a full and up-to-date list of the software and gear that I use today, check out my\n[/uses](https://nicknisi.com/uses) page.\n\n- [WezTerm](https://wezfurlong.org/wezterm/index.html) - A GPU-based terminal emulator\n- [Aerospace](https://github.com/nikitabobko/AeroSpace) - An i3-like tiling window manager for macOS.\n- [Raycast](https://raycast.com)\n\n## Questions\n\nIf you have questions, notice issues, or would like to see improvements, please\nopen a new [discussion](https://github.com/nicknisi/dotfiles/discussions/new)\nand I'm happy to help you out!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicknisi%2Fdotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicknisi%2Fdotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicknisi%2Fdotfiles/lists"}