> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dotfiles

> Apply your shell, editor, and tool configurations to every Ona environment automatically.

Dotfiles apply your personal configurations (shell settings, aliases, editor preferences, tools) to every Ona environment on startup. Your customizations layer on top of the team's standardized Dev Container, so you get a consistent base with your own workflow.

## Configure your dotfiles repository

Point Ona at a Git repository containing your dotfiles. Every new environment will clone it and run your install script automatically.

**Via CLI:**

```bash theme={null}
ona user dotfiles set --repository https://github.com/<your-user>/dotfiles
```

**Via Web UI:**

Navigate to [Settings > Preferences](https://app.ona.com/settings/preferences) and enter the repository URL.

If you do not have a dotfiles repository yet, see [GitHub's dotfiles guide](https://dotfiles.github.io) or [awesome-dotfiles](https://github.com/webpro/awesome-dotfiles) for examples.

## How dotfiles are installed

When an environment starts, Ona:

1. Clones your dotfiles repository to `~/dotfiles`
2. Runs the **first** matching script it finds:
   * `install.sh` or `install`
   * `bootstrap.sh` or `bootstrap`
   * `setup.sh` or `setup`

If none of these files exist, the repository is cloned but no script runs.

You are limited to one dotfiles repository per user.

## Update dotfiles in a running environment

Changes pushed to your dotfiles repository apply to **new** environments only. To update a running environment:

```bash theme={null}
cd ~/dotfiles && git pull && ./install.sh
```

Replace `install.sh` with whichever script your repository uses.

## Iterate on your dotfiles

To test changes without creating new environments each time:

1. Start an environment from your dotfiles repository
2. Edit files and re-run your install script to validate
3. Run `ona environment devcontainer rebuild` to reset the environment state if needed

## Change the default shell

Add this to your install script to switch to `zsh` (or any other shell):

```bash theme={null}
sudo chsh "$(id -un)" --shell "/usr/bin/zsh"
```

This modifies `/etc/passwd`, which persists across terminal sessions within the same environment.

## Best practices

* **Keep install scripts fast.** Every second adds to environment startup time.
* **Run non-interactively.** The install script runs without a TTY. Commands that prompt for input (e.g., `read`, interactive installers) will hang the environment.
* **Make scripts self-contained.** Check for dependencies before installing them, since Dev Container images vary across projects:

```bash theme={null}
FZF_VERSION="0.60.3"
if ! command -v fzf >/dev/null 2>&1; then
    curl -L "https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_amd64.tar.gz" | tar xzf -
    sudo mv fzf /usr/local/bin
fi
echo "source <(fzf --zsh)" >> "$HOME/.zshrc"
```

* **Do not store secrets in dotfiles.** Use [Ona secrets](/ona/configuration/secrets/overview) instead.

## Troubleshooting

<Accordion title="Dotfiles failed to clone">
  Check the environment logs under "Creating Dev Container" for errors. A common cause:

  ```
  fatal: repository 'https://github.com/user/dotfiles-does-not-exist/' not found
  ```

  Verify the repository URL in [Settings > Preferences](https://app.ona.com/settings/preferences) points to an existing, accessible repository.
</Accordion>

<Accordion title="Install script failed">
  Clone errors appear in the environment logs, but install script failures may not. Reproduce the error manually:

  ```bash theme={null}
  cd ~/dotfiles
  ./install.sh
  ```

  If the script works in some projects but not others, the failing project's Dev Container image is likely missing a dependency your script needs. Make your script self-contained by checking for and installing missing dependencies (see the fzf example above).
</Accordion>

<Accordion title="Environment hangs during startup">
  The install script runs in a non-interactive shell without a TTY. Commands that expect terminal input will block indefinitely.

  To diagnose:

  1. Remove your dotfiles repository from [Settings > Preferences](https://app.ona.com/settings/preferences)
  2. Start a fresh environment
  3. Clone your dotfiles and run the install script manually to find the blocking command
  4. Fix the script, push, and re-add the repository URL
</Accordion>