· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·

Configuration

Astral can be configured at multiple levels: system-wide, user-level, and per-repository. This document covers all configuration options.

---

Configuration Hierarchy

Configuration is loaded in this order (later overrides earlier):

---

Configuration File Format

Astral uses a simple key-value format:

# ~/.aslconfig

[user]
    name = John Doe
    email = john@example.com

[core]
    editor = vim
    pager = less

[diff]
    tool = vimdiff

---

Core Settings

User Identity

Required for creating commits:

[user]
    name = Your Name
    email = you@example.com

| Key | Description | Default | | :--- | :--- | :--- | | user.name | Name for commit attribution | (required) | | user.email | Email for commit attribution | (required) |

Core Behavior

[core]
    editor = vim              # Editor for commit messages
    pager = less              # Pager for log and diff
    autocrlf = false          # Line ending conversion
    filemode = true           # Track file permissions
    ignorecase = false        # Case-sensitive paths

---

Diff & Merge Settings

Diff Configuration

[diff]
    tool = vimdiff            # External diff tool
    algorithm = histogram     # Diff algorithm
    color = true              # Colored output

Merge Configuration

[merge]
    tool = vimdiff            # External merge tool
    conflictstyle = diff3     # Conflict marker style

---

Remote Settings

Configure remote repositories:

[remote "origin"]
    url = https://github.com/user/repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*

[remote "upstream"]
    url = https://github.com/org/repo.git

---

Environment Variables

Override any configuration with environment variables:

| Variable | Overrides | Example | | :--- | :--- | :--- | | ASL_AUTHOR_NAME | user.name | ASL_AUTHOR_NAME="John" | | ASL_AUTHOR_EMAIL | user.email | ASL_AUTHOR_EMAIL="j@x.com" | | ASL_EDITOR | core.editor | ASL_EDITOR="nvim" | | ASL_DIR | Repository path | ASL_DIR="/path/to/.asl" | | ASL_NO_COLOR | Disable colors | ASL_NO_COLOR=1 |

# Example: Override author for a single command
ASL_AUTHOR_NAME="Bot" ASL_AUTHOR_EMAIL="bot@ci.com" asl save -m "Automated update"

---

Managing Configuration

View Settings

# List all settings
asl config --list

# Get specific value
asl config user.name

# Show where setting comes from
asl config --show-origin user.email

Set Values

# Set global (user) setting
asl config --global user.name "John Doe"

# Set local (repo) setting
asl config --local core.editor "code --wait"

# Set system setting (requires root)
sudo asl config --system core.pager "less"

Remove Values

# Remove a setting
asl config --unset user.name

# Remove entire section
asl config --remove-section remote.old

---

Ignore Patterns

The .aslignore file specifies intentionally untracked files:

# .aslignore

# Build outputs
/build/
/dist/
*.o
*.exe

# Dependencies
/node_modules/
/vendor/

# IDE files
.idea/
.vscode/
*.swp

# OS files
.DS_Store
Thumbs.db

---

Aliases

Create command shortcuts:

[alias]
    s = status
    c = save
    l = log --oneline -10
    lg = log --oneline --graph
    co = switch
    unstage = reset HEAD --

Usage:

asl s        # Same as: asl status
asl lg       # Same as: asl log --oneline --graph

---

Next Steps