{"id":16890773,"url":"https://github.com/sds/dot","last_synced_at":"2025-08-21T08:31:38.503Z","repository":{"id":3038444,"uuid":"4059147","full_name":"sds/dot","owner":"sds","description":"Framework for managing multiple shell configurations and dot files.","archived":true,"fork":false,"pushed_at":"2022-11-09T03:28:19.000Z","size":59,"stargazers_count":45,"open_issues_count":0,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-02-20T03:21:41.368Z","etag":null,"topics":["bash","dotfiles","fish","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sds.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}},"created_at":"2012-04-18T01:43:43.000Z","updated_at":"2025-02-14T15:50:24.000Z","dependencies_parsed_at":"2023-01-11T16:14:00.449Z","dependency_job_id":null,"html_url":"https://github.com/sds/dot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sds/dot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sds%2Fdot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sds%2Fdot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sds%2Fdot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sds%2Fdot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sds","download_url":"https://codeload.github.com/sds/dot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sds%2Fdot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271449245,"owners_count":24761639,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","fish","zsh"],"created_at":"2024-10-13T17:04:21.253Z","updated_at":"2025-08-21T08:31:38.206Z","avatar_url":"https://github.com/sds.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dot\n\nDot is a framework for managing your user configuration files and environment\n(usually referred to as \"dotfiles\").\n\nDot supports a powerful plugin system allowing authors to write plugins that\nwork with multiple different shells and operating systems.\n\n## Installation\n\nYou'll need a POSIX-compliant shell (e.g. `sh`) to perform the initial\ninstallation, but otherwise any of the following shells are supported:\n\n* Bash\n* Zsh\n* Fish\n\nThe easiest way to get started is to clone\n[my personal dot files](https://github.com/sds/.files) and clear out the\n`plugins` directory so you start with a clean slate.\n\n```bash\ngit clone --recurse-submodules https://github.com/sds/.files ~/.files\ncd ~/.files\nrm -rf plugins/*\nbin/install\n```\n\nDot's architecture allows it to support any kind of shell. If you don't see a\nshell you use here, feel free to add support for it in a pull request!\n\nInstalling Dot will create a `.files` directory in your current user's home\ndirectory. Inside that directory will be a `plugins` directory which you\ncan fill with as many subdirectories for each plugin you write. These\ndirectories can be other Git repositories, for example.\n\nAlso in the `.files` directory is a `framework` directory which is this repository\n(stored as a Git submodule). This allows you to easily update to newer versions\nof the framework but keep it otherwise separated from your personal plugins.\n\nDepending on the shell you use, your various shell startup files\n(`~/.bashrc`, `~/.zshrc`, etc.) will be symlinked into a corresponding file\nin the `framework` directory. This allows Dot to link into your shells\nstartup sequence to load the relevant code from your plugins.\n\n* [Bash Startup Files](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html)\n* [Zsh Startup Files](http://zsh.sourceforge.net/Intro/intro_3.html)\n* [Fish Startup Files](http://fishshell.com/docs/current/tutorial.html#tut_startup)\n\n## Plugin structure\n\nA plugin is simply a directory in your `$DOT_HOME/plugins` directory containing\nappropriate scripts and configuration. Plugins can contain configuration for\nmultiple shells and operating systems.\n\nThe following directories within the plugin directory have special meaning to Dot:\n\nDirectory                 | Purpose\n--------------------------|-----------------------------------------------------\n`bin`                     | Executables to add to `PATH` after installing plugin\n`env`                     | Environment variables to set when loading plugin (regardless of shell context)\n`env/login`               | Environment variables to set when initializing a login shell\n`env/interactive`         | Environment variables to set when initializing an interactive shell\n`env/setup`               | Environment variables to set during both install/uninstall\n`env/setup/install`       | Environment variables to set during install\n`env/setup/uninstall`     | Environment variables to set during uninstall\n`lib`                     | Scripts to source when loading plugin (regardless of shell context)\n`lib/login`               | Scripts to source when initializing a login shell\n`lib/logout`              | Scripts to source when exiting a login shell\n`lib/interactive`         | Scripts to source when initializing an interactive shell\n`libexec`                 | Support executables to always add to `PATH` when loading plugin\n`libexec/setup`           | Support executables to add to `PATH` during both install/uninstall\n`libexec/setup/install`   | Support executables to add to `PATH` during install\n`libexec/setup/uninstall` | Support executables to add to `PATH` during uninstall\n`setup`                   | Executables to execute during install/uninstall\n`setup/install`           | Executables to execute during install\n`setup/uninstall`         | Executables to execute during uninstall\n\nThe following files within the plugin directory have special meaning to Dot:\n\nFile                 | Purpose\n---------------------|-----------------------------------------------------------------\n`dependencies`       | List of plugins that must be loaded _before_ this plugin is loaded.\n`platforms`          | List of operating systems this plugin supports.\n\nThe `dependencies` file is especially useful if you want to have plugins\nexpose helper functions or environment variables that are used by other\nplugins. Ensuring that those plugins are loaded (and their\nfunctions/environment variables set) before other plugins are run allow\nyou to support better separation of responsibility.\n\nThe `platforms` file is useful if a plugin is operating system-specific.\nFor example, if a plugin only works on macOS, you should add a `platforms`\nfile to the plugin containing the line `mac`.\n\n### Aliases, functions, and executables\n\nMost shells have the concept of aliases and functions, so it can be a bit\nconfusing when you should use one over the other. This section aims to\nprovide clear guidelines about use cases for each type and how they compare\nto standard executables.\n\n#### Aliases\n\nAliases should be thought of as simple shortcuts, e.g. setting `g` = `git`\nfor making it easier to execute common commands in your shell.\n\nYou should use an alias when you want the auto-completions for the aliased\ncommand to continue work.\n\n#### Functions\n\nFunctions are shell helpers that can modify environment variables in your\nshell or perform other useful things specific to your shell.\n\n#### Executables\n\nIf the command you're thinking of isn't a shortcut (i.e. alias) or setting\nenvironment variables in your actual shell, you should use an executable.\nThis doesn't need to be a compiled binary, but can be a script with\nexecutable permissions and a [shebang line][Shebang] at the top, e.g.\n\n```bash\ncat \u003e my-executable \u003c\u003cEOF\n#!/usr/bin/env sh\necho \"My very own executable!\"\nEOF\nchmod +x my-executable\n```\n\nThe advantage of using executables is that they are isolated and aren't\nloaded until you attempt to execute them, reducing the time it takes\nfor your shell to start up.\n\n## Shell contexts\n\nImportant to the use of Dot is understanding the different contexts in which\na shell can run. Some quick definitions:\n\n* **Login shell**:\n  A shell which is typically spawned when you first login to a system via\n  the `login` command (e.g. when you connect to a host via `ssh` or open\n  a terminal on your machine for the first time).\n\n* **Interactive shell**:\n  A shell whose standard input stream is connected to a console/TTY, and thus\n  is able to receive input from a user.\n\nThese definitions are not mutually exclusive--a shell can be both a login\nshell _and_ an interactive shell, one of the two, or neither!\n\nHere are same examples for the `bash` shell (your shell's behavior may be different):\n\nCommand                       | Login         | Interactive\n------------------------------|:-------------:|:----------:\n`-bash` †                     |  ✅            | ✅\n`bash -l`                     |  ✅            | ✅\n`bash -i`                     |               | ✅\n`bash -li`                    |  ✅            | ✅\n`bash -c \"some-command\"`      |               |\n`bash -lc \"some-command\"`     |  ✅            |\n`bash -ic \"some-command\"`     |               | ✅\n`bash -lic \"some-command\"`    |  ✅            | ✅\n\n† *Starting a shell with a leading `-` is done via the\n[`login`](https://linux.die.net/man/1/login) command*\n\n\n## Writing a Plugin\n\nWriting your own plugin with Dot is designed to be easy. To start, you need\nto identify what you want your plugin to do.\n\n  * Does it install files in your home directory?\n  * Does it set any environment variables?\n  * Does it declare any aliases or functions for use in your shell?\n\nIf you're installing any sort of files or repository, you'll need to add a\nscript to your plugin's `setup` directory and then use Dot's various helpers\n(e.g. `dot::symlink`) to install the files.\n\n## Motivations\n\nDot was motivated by the desire to:\n\n* Save setup time on new systems\n\n* Provide a flexible framework for organizing a large number of configuration\n  files\n\n* Allow easy switching between shells when pair programming (for example\n  if one pair prefers a different shell) without breaking all of your\n  configuration\n\n* Learn more about the idiosyncrasies of various shells\n\n## Frequently Asked Questions\n\n* **How is Dot different from other config management systems? (Ansible/Chef/etc.)**\n  Dot tries to carve out a niche specifically for configuring a\n  personal/development machine for a single user. However, at its core it's\n  accomplishing similar goals to full-blown config management systems.\n\n  If you need the additional bells and whistles provided by those tools, you\n  should use them. However, state of the art for these tools constantly changes\n  and is hard to keep up with. Shell languages on the other hand, are\n  relatively static, so code you write for Dot will likely serve you longer.\n\n* **Why is my favorite shell not supported?**\n  Support for additional shells is a pull request away. If your shell is\n  POSIX-compatible it might be easier than you think, as many of the\n  routines used by Dot are written in POSIX-compatible shell script.\n\n  Check out the `shells` directory in `lib`/`libexec` to see the code required\n  to support each shell.\n\n## Etymology\n\nDot comes from the fact that it was originally designed to manage user 'dot'\nfiles, and is a tribute to [Dot Matrix][DotMatrix] of [ReBoot][ReBoot] fame.\n\n## License\n\nDot is released under the terms of the [Apache 2.0 license](LICENSE).\n\n[DotMatrix]: http://reboot.wikia.com/wiki/Dot_Matrix\n[ReBoot]: http://en.wikipedia.org/wiki/ReBoot\n[Shebang]: https://en.wikipedia.org/wiki/Shebang_(Unix)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsds%2Fdot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsds%2Fdot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsds%2Fdot/lists"}