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

Quick Start

⏱
5 Minutes
Time to complete this guide

Get up and running with Astral in minutes. This guide will walk you through installation, initialization, and your first commits.

Prerequisites

Before installing Astral, ensure you have:

  • Operating System: macOS, Linux, or Windows (with WSL)
  • Build tools: make, go 1.21+ (for building from source)
  • Terminal access: bash, zsh, or PowerShell

Installation

Option 1: From Source (Recommended)

Clone the repository and build:

# Clone the repository
git clone https://github.com/codimo/astral.git
cd astral

# Build and install
make build
make install

# Verify installation
asl version
Expected Output
Astral VCS v0.1.0-alpha (build: 2025-01-15)

Option 2: Using Go

If you have Go installed:

go install github.com/codimo/astral/cmd/asl@latest

Option 3: Download Binary

Download pre-built binaries from our releases page.

Initialize a Repository

Navigate to your project directory and initialize Astral:

cd your-project
asl init

This creates an .asl directory containing:

.asl/

├──objects/Content-addressable storage
├──refs/Branch and tag pointers
├──HEADCurrent branch reference
└──configRepository configuration

Your First Save

Unlike Git, Astral has no staging area. Saving is direct:

# Make some changes to your files
echo "Hello, Astral" > README.md

# Save your changes directly
asl save -m "Initial commit"
Terminal Output
$ asl save -m "Initial commit"
✓ Saved: 8f2a1c3d
1 file changed, 1 insertion

View Your History

See your commit history with:

asl log

Or view the stack visualization:

asl stack
Stack Visualization
  @ 8f2a1c3d (HEAD) Initial commit
|
o (main) [empty]

Make More Changes

Continue working naturally:

# Create more files
echo "# My Project" >> README.md
touch src/main.go

# Save again
asl save -m "Add project structure"

# View the growing stack
asl stack

Common Workflow Commands

Command
Description
Git Equivalent
asl save
Save all changes
git add . && git commit
asl status
View working state
git status
asl log
View history
git log
asl diff
Show changes
git diff
asl branch
Manage branches
git branch

Next Steps

You've successfully:

  • ✓ Installed Astral
  • ✓ Initialized a repository
  • ✓ Made your first commits
Continue Learning

Dive deeper into Astral's unique concepts and features.

Learn about Stacks →

CLI Reference →

└─── End of Document ───┘