dotly

Dotly uses an opinionated directory structure to organize your configurations:

• bin/: External binaries or symlinks (takes precedence in $PATH).
• doc/: Documentation for your dotfiles.
• editors/: Settings for editors (e.g., VSCode, IntelliJ).
• git/: Git configurations.
• langs/: Configurations for programming languages and libraries.
• os/: OS-specific configurations or app settings.
• restoration_scripts/: Scripts executed during restoration on new machines.
• scripts/: Your custom user scripts.
• shell/: Shell configuration files (Bash, Zsh, Fish).
• symlinks/: Configuration for your symlinks.

To manage application configuration files (like VSCode settings) via dotly, follow this two-step process:

1. Move the config to your dotfiles folder to make it the source of truth: cp ~/path/to/app/config $DOTFILES_PATH/editors/app/config.json

2. Create a symlink by editing $DOTFILES_PATH/symlinks/conf.YOUR-OS.yaml. Add an entry in the format ORIGINAL_PATH: DOTLY_PATH_RELATIVE_TO_DOTFILES: ~/Library/Application Support/Code/User/settings.json: editors/code/settings.json

If you already have a dotfiles repository, follow these steps to restore it using dotly:

1. Install git.
2. Clone your repository to $HOME/.dotfiles.
3. Navigate to the folder: cd $HOME/.dotfiles.
4. Initialize submodules: git submodule update --init --recursive modules/dotly.
5. Run the dotly install command: DOTFILES_PATH="$HOME/.dotfiles" DOTLY_PATH="$DOTFILES_PATH/modules/dotly" "$DOTLY_PATH/bin/dot" self install.
6. Restart your terminal.
7. Import packages: dot package import.

To test dotly in a disposable environment, you can use Docker. Once you exit the zsh session, the image is deleted.

# Using Alpine
docker run -e TERM -e COLORTERM -e LC_ALL=C.UTF-8 -w /root -it --rm alpine sh -uec '
  apk add curl sudo bash zsh git g++ python3
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/CodelyTV/dotly/HEAD/installer)"
  zsh'

# Or using Ubuntu
docker run -e TERM -e COLORTERM -w /root -it --rm ubuntu sh -uec '
  apt-get update
  apt-get install -y curl build-essential sudo
  su -c bash -c "$(curl -fsSL https://raw.githubusercontent.com/CodelyTV/dotly/HEAD/installer)"
  su -c zsh'

If you prefer to set up your environment step-by-step, follow these instructions to clone your repository and use the dot binary to install your configuration. This process assumes you have git installed and that your dotfiles are stored in a git repository.

1. Clone your repository to $HOME/.dotfiles.
2. Navigate to the directory.
3. Initialize the dotly submodule.
4. Execute the self install command using the dot binary located in the submodule.
5. Restart your terminal.
6. Import your packages using dot package import.

git clone [your repository of dotfiles] $HOME/.dotfiles
cd $HOME/.dotfiles
git submodule update --init --recursive modules/dotly
DOTFILES_PATH="$HOME/.dotfiles" DOTLY_PATH="$DOTFILES_PATH/modules/dotly" "$DOTLY_PATH/bin/dot" self install
# Restart terminal
dot package import

You can automate the restoration process using a single command. The restorer script handles the setup for you.

Requirements:

• If your repository is private, you must have your GitHub username, repository name, and SSH key configured.
• If using a non-GitHub repository, you must know the git repository URL.

Using wget:

bash <(wget -qO- https://raw.githubusercontent.com/CodelyTV/dotly/HEAD/restorer)

Using curl:

bash <(curl -s https://raw.githubusercontent.com/CodelyTV/dotly/HEAD/restorer)

You can customize the dotly theme by modifying parameters in your shell/exports.sh file. Supported parameters include:

• CODELY_THEME_MINIMAL: true|false (If true, only shows prompt status).
• CODELY_THEME_MODE: `

If you run dot without arguments or with only a <context>, the tool uses fzf to provide an interactive prompt.

• dot: Lists all available scripts across all contexts. You can use the preview window to see the help documentation for a script before selecting it.
• dot <context>: Filters the interactive list to only show scripts belonging to the specified <context>.

##?    dot
##?    dot <context>

The dot command is the primary interface for dotly. It is used to execute various scripts and manage your configuration.

Usage:

• dot: Lists available scripts.
• dot <context> <script> [<args>...]: Executes a specific script within a context.
• dot -h | --help: Shows help information.

To run a specific script without interactive selection, provide the <context> and the <script> name. Any subsequent arguments will be passed directly to the script. The CLI searches for the script in the following order:

1. $DOTFILES_PATH/<context>/scripts/<script>
2. $DOTLY_PATH/<context>/scripts/<script>

If the script is not found in either location, an error is returned.

dot <context> <script> [<args>...]