Skip to content

UV_INIT_GUIDE.md

Latest commit

 

History

History
111 lines (88 loc) · 2.82 KB

UV_INIT_GUIDE.md

File metadata and controls

111 lines (88 loc) · 2.82 KB

Why Use uv init --vcs none?

The Problem with Default uv init

By default, uv init creates a git repository for each project:

uv init new-topic  # Creates topics/new-topic/.git/

This would result in:

topics/
├── fizzbuzz/
│   ├── .git/           # ❌ Separate git repo
│   └── ...
├── algorithms/
│   ├── .git/           # ❌ Another separate git repo  
│   └── ...

Our Solution: uv init --vcs none

Using --vcs none prevents individual git repos:

uv init --app new-topic --vcs none

This gives us:

learn-python/           # ✅ Single git repo for everything
├── .git/
├── topics/
│   ├── fizzbuzz/       # ✅ No separate .git/
│   ├── algorithms/     # ✅ No separate .git/
│   └── ...

Benefits of Our Approach

✅ Single Learning History

  • All topics in one git timeline
  • Easy to see learning progression
  • Simple branching strategy

✅ Better for Learning

  • Compare implementations across topics
  • Share common utilities between topics
  • One place for all Python learning progress

✅ Cleaner Workflow

# One command to see all learning progress
git log --oneline

# Easy to branch for experiments
git checkout -b experiment/optimize-fizzbuzz

# Simple to share entire learning repo
git remote add origin https://github.com/user/learn-python

What uv init --app topic --vcs none Creates

topics/new-topic/
├── .python-version     # Python version pinning
├── main.py            # Entry point with basic structure  
├── pyproject.toml     # Modern Python project config
└── README.md          # Topic-specific documentation

Plus after uv add --dev pytest:

├── .venv/             # Isolated virtual environment
└── uv.lock           # Dependency lock file

Why This is Better Than Manual Templates

Manual Template uv init
❌ Static template to copy ✅ Fresh, up-to-date structure
❌ Manual version updates ✅ Automatic Python version detection
❌ Basic pyproject.toml ✅ Modern pyproject.toml with best practices
❌ No entry point ✅ Proper main.py with main check
❌ Generic README ✅ Topic-specific README template

Full Recommended Workflow

# Start new topic
git checkout -b topic/data-structures
cd topics/
uv init --app data-structures --vcs none
cd data-structures/

# Add testing capability
uv add --dev pytest
uv sync

# Work on your implementation...
# Save progress
git add .
git commit -m "Add binary tree implementation"

# When complete
git checkout main
git merge topic/data-structures

This gives you the best of both worlds: modern Python tooling with uv init and centralized learning history with our git setup!