Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sds/dot

Framework for managing multiple shell configurations and dot files.
https://github.com/sds/dot

bash dotfiles fish zsh

Last synced: about 1 month ago
JSON representation

Framework for managing multiple shell configurations and dot files.

Awesome Lists containing this project

README 

        
# Dot



Dot is a framework for managing your user configuration files and environment

(usually referred to as "dotfiles").



Dot supports a powerful plugin system allowing authors to write plugins that

work with multiple different shells and operating systems.



## Installation



You'll need a POSIX-compliant shell (e.g. `sh`) to perform the initial

installation, but otherwise any of the following shells are supported:



* Bash

* Zsh

* Fish



The easiest way to get started is to clone

[my personal dot files](https://github.com/sds/.files) and clear out the

`plugins` directory so you start with a clean slate.



```bash

git clone --recurse-submodules https://github.com/sds/.files ~/.files

cd ~/.files

rm -rf plugins/*

bin/install

```



Dot's architecture allows it to support any kind of shell. If you don't see a

shell you use here, feel free to add support for it in a pull request!



Installing Dot will create a `.files` directory in your current user's home

directory. Inside that directory will be a `plugins` directory which you

can fill with as many subdirectories for each plugin you write. These

directories can be other Git repositories, for example.



Also in the `.files` directory is a `framework` directory which is this repository

(stored as a Git submodule). This allows you to easily update to newer versions

of the framework but keep it otherwise separated from your personal plugins.



Depending on the shell you use, your various shell startup files

(`~/.bashrc`, `~/.zshrc`, etc.) will be symlinked into a corresponding file

in the `framework` directory. This allows Dot to link into your shells

startup sequence to load the relevant code from your plugins.



* [Bash Startup Files](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html)

* [Zsh Startup Files](http://zsh.sourceforge.net/Intro/intro_3.html)

* [Fish Startup Files](http://fishshell.com/docs/current/tutorial.html#tut_startup)



## Plugin structure



A plugin is simply a directory in your `$DOT_HOME/plugins` directory containing

appropriate scripts and configuration. Plugins can contain configuration for

multiple shells and operating systems.



The following directories within the plugin directory have special meaning to Dot:



Directory                 | Purpose

--------------------------|-----------------------------------------------------

`bin`                     | Executables to add to `PATH` after installing plugin

`env`                     | Environment variables to set when loading plugin (regardless of shell context)

`env/login`               | Environment variables to set when initializing a login shell

`env/interactive`         | Environment variables to set when initializing an interactive shell

`env/setup`               | Environment variables to set during both install/uninstall

`env/setup/install`       | Environment variables to set during install

`env/setup/uninstall`     | Environment variables to set during uninstall

`lib`                     | Scripts to source when loading plugin (regardless of shell context)

`lib/login`               | Scripts to source when initializing a login shell

`lib/logout`              | Scripts to source when exiting a login shell

`lib/interactive`         | Scripts to source when initializing an interactive shell

`libexec`                 | Support executables to always add to `PATH` when loading plugin

`libexec/setup`           | Support executables to add to `PATH` during both install/uninstall

`libexec/setup/install`   | Support executables to add to `PATH` during install

`libexec/setup/uninstall` | Support executables to add to `PATH` during uninstall

`setup`                   | Executables to execute during install/uninstall

`setup/install`           | Executables to execute during install

`setup/uninstall`         | Executables to execute during uninstall



The following files within the plugin directory have special meaning to Dot:



File                 | Purpose

---------------------|-----------------------------------------------------------------

`dependencies`       | List of plugins that must be loaded _before_ this plugin is loaded.

`platforms`          | List of operating systems this plugin supports.



The `dependencies` file is especially useful if you want to have plugins

expose helper functions or environment variables that are used by other

plugins. Ensuring that those plugins are loaded (and their

functions/environment variables set) before other plugins are run allow

you to support better separation of responsibility.



The `platforms` file is useful if a plugin is operating system-specific.

For example, if a plugin only works on macOS, you should add a `platforms`

file to the plugin containing the line `mac`.



### Aliases, functions, and executables



Most shells have the concept of aliases and functions, so it can be a bit

confusing when you should use one over the other. This section aims to

provide clear guidelines about use cases for each type and how they compare

to standard executables.



#### Aliases



Aliases should be thought of as simple shortcuts, e.g. setting `g` = `git`

for making it easier to execute common commands in your shell.



You should use an alias when you want the auto-completions for the aliased

command to continue work.



#### Functions



Functions are shell helpers that can modify environment variables in your

shell or perform other useful things specific to your shell.



#### Executables



If the command you're thinking of isn't a shortcut (i.e. alias) or setting

environment variables in your actual shell, you should use an executable.

This doesn't need to be a compiled binary, but can be a script with

executable permissions and a [shebang line][Shebang] at the top, e.g.



```bash

cat > my-executable <