{"id":13707071,"url":"https://github.com/evanpurkhiser/dots","last_synced_at":"2025-04-06T12:08:26.542Z","repository":{"id":12532550,"uuid":"15202513","full_name":"evanpurkhiser/dots","owner":"evanpurkhiser","description":"A portable tool for managing a single set of dotfiles in an organized fashion","archived":false,"fork":false,"pushed_at":"2024-07-02T04:11:48.000Z","size":218,"stargazers_count":270,"open_issues_count":8,"forks_count":38,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-10-14T02:49:26.660Z","etag":null,"topics":["dotfile-manager","dotfiles","python"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ccforward/cc","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evanpurkhiser.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2013-12-15T11:48:12.000Z","updated_at":"2024-07-08T02:06:23.000Z","dependencies_parsed_at":"2024-10-25T18:35:50.135Z","dependency_job_id":"05b5af84-bb95-4314-af67-88b4eaafa26f","html_url":"https://github.com/evanpurkhiser/dots","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanpurkhiser%2Fdots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanpurkhiser%2Fdots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanpurkhiser%2Fdots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evanpurkhiser%2Fdots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evanpurkhiser","download_url":"https://codeload.github.com/evanpurkhiser/dots/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478322,"owners_count":20945266,"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":["dotfile-manager","dotfiles","python"],"created_at":"2024-08-02T22:01:17.786Z","updated_at":"2025-04-06T12:08:26.525Z","avatar_url":"https://github.com/evanpurkhiser.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## ⚠️ NOTE\n\n\u003e I have rewrote this tool in go, you can still find the old python 2.x version\n\u003e of this tool on the `releases/1.x` branch. The readme below **is still for\n\u003e the 1.x version of this tool!**\n\n# Dots - A dotfile Management Tool\n\nTODO: Add contents section here\n\nIn the desktop \\*nix world \"dotfiles\" are the life and blood behind the\ncustomization of your environment. Everything from custom bash prompts to window\nmanager configurations, dotfiles define your work flow. Because of this, it has\nbecome a very common practice to keep your dotfiles in a git repository and even\nmake the repository available on GitHub for the community to explore.\n\n### The Problem\n\nKeeping your dotfiles in a git repository can prove to be rather difficult\nhowever. Because dotfiles can be spread all across the users `$HOME` the\nprocess of tracking these files can be tedious. A few strategies have emerged\nwithin the community that offers command over dotfiles:\n\n- Keeping `$HOME` under git version control - This can be difficult and\n  dangerous as every directory under your `$HOME` now appears to be in version\n  control, so running a `git` command will never fail.\n\n- Keeping the `$XDG_CONFIG_HOME` directory under version control and using\n  environment variables and scripts to force programs to read their\n  configurations from the `$XDG_CONFIG_HOME` directory - A great overall\n  strategy that keeps dotfiles more organized than keeping them in `$HOME`.\n\n- Keeping dotfiles in a directory under `$HOME` and writing an 'installation'\n  script to symbolically link the files to their appropriate location in the\n  users `$HOME` - While this method is rather robust, it can be difficult to\n  manage a installation script specifically for your dot files, and may impose\n  limits in how you organize your dotfiles.\n\nHowever, none of these methods offer any sort of ability to manage dot files\nacross multiple machines and environments. While you can use any one of these\nstrategies to effectively manage dotfiles for a single machine, using the same\ndotfiles on another machine _will be_ convoluted and cumbersome.\n\nFor example, say you manage a set of dotfiles for your desktop machine that\nincludes configuration for bash, Vim, a window manager, and GTK theme settings.\nIf you would like to use these dotfiles in a headless server environment then\nyou would obviously not need your window manager and GTK configurations. Even\nworse, changes may need to be made to some of the configuration files for that\nspecific environment.\n\n### The Solution\n\nThe `dots` utility aims to help make the installation, revision control, and\norganization of dot files easy and intuitive. The dots utility solves all of the\nproblems that the solutions mentioned above solve while also facilitating the\nability to maintain a single repository of dotfiles that can be installed on any\nmachine you access and would like to have your environment configured in a snap.\n\n`dots` offers the following features:\n\n- **Configuration groups**  \n  When installing your dotfiles onto a new machine, `dots` offers you the\n  ability to select a specific 'group' of dotfiles that you would like to have\n  installed into that environment. By organizing your dotfiles into logical\n  groups (such as 'machine' groups) it's possible to only install the dotfiles\n  that are required by that environment.\n\n- **Cascading file structure**  \n  By selecting multiple configuration groups there is the possibility that two\n  groups both contain a dotfile with matching names. For example, if two\n  configuration groups both contain a `bashrc` file then the `dots` utility\n  will automatically merge these two files together. A special syntax is also\n  offered to allow for one file to override another or for the cascading files\n  to be merged into the files at specific points.\n\n- **Follows [XDG Base Directory Standard](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)**  \n  The XDG Base Directory Standard specifies that all configuration files should\n  be located in the `$XDG_CONFIG_HOME` directory. By default, this is where all\n  configuration files and directories will be installed. While this does\n  require a little extra work to ensure all programs read their configuration\n  files from here it offers a much more organized view of user dotfiles.\n\n- **Post installation scripts per file**  \n  It's possible to include a `.install` script with any specific dotfile or\n  directory. This installation script will be executed any time the specific\n  dotfile is installed. This is useful for situations where you _need_ to\n  symbolically link a configuration file into `$HOME` or if something needs to\n  be done after installation (for example executing :BundleInstall for VIM).\n\nThese features are expanded on below.\n\n## Usage and configuration\n\n**NOTE:**\nFor a quick and easy way to get going managing your dot files more effectively\nsee the [dots-template](https://github.com/evanpurkhiser/dots-template)\nrepository that offers instructions for getting setup.\n\n---\n\nIt's recommended to read through the entirety of this README to have a good\nunderstanding of how the dots management utility works. Here are a few key points\nto keep in mind however:\n\n- Configuration files will be installed into `$XDG_CONFIG_HOME`.\n- Configuration group directories are to be located in `$HOME/.local/etc`.\n- A PKGBUILD file is also available for Arch Linux [on the\n  AUR](https://aur.archlinux.org/packages/dots-manager/).\n- The `dots` binary should be made available in your `PATH`.\n- The `dots` binary should support Python \u003e 2.7 / Python \u003e 3.2.\n- See [Evan Purkhisers personal\n  dotfiles](https://github.com/evanpurkhiser/dots-personal) for an example\n  configuration.\n\nFor details on using the `dots` tool itself see the `dots help` [USAGE\noutput](bin/dots#L83).\n\n### The initialization bootstrap script\n\nA [initialization script](contrib/initialize) is included in the `contrib`\ndirectory, providing an easy way to initialize your dotfiles into the proper\ndirectory, temporarily setup the `PATH` for the dots, and temporarily source the\nbash completion scripts. This way you can quickly setup your dotfiles, activate\nyour configuration groups, and install the dotfiles themselves\n\nFor example:\n\n```sh\n$ cd ~\n$ git clone https://github.com/Your/Dotfiles\n$ DOTS_CLONE_DIR=~/Dotfiles\n$ source dots/contrib/initialize\n```\n\nThis will do the following:\n\n1.  Move the Dotfiles into `$HOME/.local/etc`\n2.  Symbolically link the dots executable into `$HOME/.local/bin`\n3.  Add `$HOME/.local/bin` into the `PATH` if it's not already\n4.  Source the `contrib/bash_completion` script\n\nYou can then setup your dotfiles using the `dots` command:\n\n```sh\n$ dots groups set base machines/desktop\n$ dots install\n```\n\n### Bash completion\n\nA bash [completion script](dots/blob/releases/1.x/contrib/bash_completion) is included and provides\ncompletions for all aspects of the `dots` command. If you would like to take\nadvantage of this it's recommended that you source this file in your `bashrc`.\n\n## Configuration groups\n\nThe primary feature of the dots utility is to allow for dotfiles to be organized\ninto different \"Configuration groups\". These configuration groups can then be\nenabled or disabled for the specific environment that the dotfiles are being\ninstalled into.\n\nConfiguration groups are two-level directories containing configuration files\nand directories that will be installed when the group is activated. The dots\nutility also includes a special configuration group that is hard coded into the\nutility: The `base` group is a single-level directory, so all files and\ndirectories located in the `base` directory will be installed if the base group\nis activated.\n\n## Extending and Overriding configurations\n\nConfiguration groups can override or extend files that are included in\nconfiguration groups specified prior to them.\n\n### Extending configuration files\n\nIf a configuration file in the `base` group specifies _most_ of what is needed,\nbut for the specific environment you're installing the configuration files into\nrequires a little extra configuration for that file it is possible to append to\nit.\n\nFor example, if you would like to add more options to the `bashrc` for your\n`machine/desktop` group, you can simply include the `bash/bashrc` file and it\nwill automagically be appended to the `base/bash/bashrc` file upon installation.\n\nShebangs will be removed from the first line of the file being appended.\n\n### Overriding\n\nYou can completely override a configuration file included in a previous group.\nThis is similar to extending a configuration file as described in the previous\nsection, however the file will simply replace the file specified in the\nenvironment group.\n\nEnable overriding for a file by appending `.override` to the filename.\n\n## Installation Scripts\n\nFor each configuration file you may also include a `.install` script. This file\nwill be executed when the specific configuration file has been installed. If the\ndestination file has not been changed from the compiled file then the install\nscript will not be executed.\n\nThe installation scripts will be executed with the destination directory as the\ncurrent working directory. In order for the scripts to be executed, they must\nbe executable and include a shebang.\n\nFor example: We have a `base/vim/vimrc` configuration file. We could also\ninclude a `base/vim/vimrc.install` file that executes some commands when the\nvimrc file is installed. The script will be executed with the\n`$XDG_CONFIG_HOME/vim/` as the working directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanpurkhiser%2Fdots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevanpurkhiser%2Fdots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevanpurkhiser%2Fdots/lists"}