Git Repo Tool Implementation for Z-Tools: Complete Guide Index

Comprehensive documentation set for implementing Google’s Git Repo tool for z-tools portfolio management.

Documentation Files

1. REPO_TOOL_GUIDE.md - Complete Reference

Purpose: Comprehensive reference manual for repo tool concepts, architecture, and commands

Contents:

  • Overview and why repo for z-tools
  • Architecture (three-tier structure, key components)
  • Installation instructions (Linux, macOS)
  • Complete setup guide for z-tools
  • Manifest file reference (XML syntax, attributes)
  • Common repo workflows with explanations
  • Advanced manifest patterns
  • Command reference (core commands, forall usage)
  • Z-tools specific examples
  • CI/CD integration patterns
  • Best practices and troubleshooting
  • Next steps for implementation

When to Use:

  • First-time repo setup
  • Understanding concepts and architecture
  • Reference for manifest syntax
  • Learning best practices
  • Troubleshooting issues

2. REPO_TOOL_TUTORIAL.md - Hands-On Tutorial

Purpose: Step-by-step tutorial with complete, copy-paste examples

Contents:

  • Prerequisites and installation (with verification)
  • Initial setup walkthrough:
    • Prepare manifest repository
    • Create .gitignore
    • Create default manifest file
    • Initialize repo workspace
    • Verify installation
  • Common workflows with full examples:
    • Feature development across multiple projects
    • Selective project operations
    • Bug fixes across all projects
  • Release management workflow (v0.7.0 example)
  • Team collaboration patterns
  • Automation scripts (release.sh, sync-all.sh)
  • Tips, tricks, and aliases
  • Summary of key commands

When to Use:

  • Setting up repo for first time
  • Learning through hands-on examples
  • Copy-paste ready commands
  • Understanding workflow sequences
  • Creating team training materials

3. REPO_TOOL_ADVANCED.md - Advanced Patterns

Purpose: Advanced workflows and optimization patterns

Contents:

  • Multi-manifest strategy (dev, release, docs, CI tracks)
  • Development environments (lightweight, focused, profile-based)
  • CI/CD integration (GitHub Actions workflow example)
  • Complex workflows (multi-team coordination, large refactoring)
  • Performance optimization (fast sync, caching, workspace size)
  • Troubleshooting advanced issues
  • Helpful aliases and functions for ~/.bashrc
  • Repository statistics tools

When to Use:

  • Optimizing for large teams
  • Complex multi-track development
  • Performance issues with large repositories
  • Advanced CI/CD integration
  • Troubleshooting unusual scenarios

4. manifest-default.xml - Ready-to-Use Manifest

Purpose: Production-ready manifest file for z-tools

Contents:

  • Fully documented XML manifest
  • All four z-tools projects configured
  • Remote definitions (GitHub)
  • Project groups (python, rust, tools, manifests)
  • Project annotations (description, language, package-manager)
  • Comprehensive comments explaining each section
  • Manifest syntax reference

How to Use:

  1. Copy file content
  2. Place in z-tools repository on manifest branch at manifests/default.xml
  3. Commit and push
  4. Use with repo init -m manifests/default.xml

Quick Start (5 Minutes)

1. Install Repo

1
2
3
4
5

mkdir -p ~/.local/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.local/bin/repo
chmod a+x ~/.local/bin/repo
export PATH="$HOME/.local/bin:$PATH"
repo --version

2. Set Up Manifest in z-tools

1
2
3
4
5
6
7

cd ~/z-tools-manifests  # (or wherever z-tools is)
git checkout -b manifest
mkdir -p manifests
# Copy manifest-default.xml content to manifests/default.xml
git add .
git commit -m "chore: add manifest for repo tool"
git push origin manifest

3. Initialize Workspace

1
2
3

mkdir ~/z-tools-repo && cd ~/z-tools-repo
repo init -u git@github.com:pilakkat1964/z-tools.git -b manifest
repo sync

4. Try It Out

1
2
3

repo list              # See all projects
repo status            # Check status
repo branches          # See branches

Done! You now have all four z-tools projects synchronized.

Common Tasks

Create Feature Branch

1
2
3

repo start feature/my-feature
# Make changes in any project
repo forall -c git push origin feature/my-feature

Work on Python Only

1
2

repo sync -g python
repo forall -g python -c pytest

Release New Version

1
2
3
4

repo start release/v0.7.0
# Update versions in each project
repo forall -c git tag -a v0.7.0 -m "Release v0.7.0"
repo forall -c git push origin v0.7.0

See All Changes

1

repo forall -c 'echo "=== $REPO_PROJECT ===" && git status'

Architecture Overview

1
2
3
4
5
6
7
8
9
10
11
12
13
14

GitHub Repositories
├── z-tools (manifest branch)
│   └── manifests/default.xml
├── z-edit (master)
├── z-open (master)
├── z-kitty-launcher (master)
└── z-rclone-mount-applete (main)
        ↓ (repo tool manages)
Local Workspace (~z-tools-repo)
├── .repo/                 (metadata)
├── z-edit/                (synced)
├── z-open/                (synced)
├── z-kitty-launcher/      (synced)
└── z-rclone-mount-applete/ (synced)

When to Use Each Document

Situation Document Section
First time setup TUTORIAL Initial Setup
Don’t understand concepts GUIDE Overview & Architecture
Need to create manifest GUIDE Manifest File Reference
Copy-paste commands TUTORIAL Common Workflows
Optimize performance ADVANCED Performance Optimization
Team training TUTORIAL All sections
Troubleshoot issues GUIDE/ADVANCED Troubleshooting
Complex workflow ADVANCED Complex Workflows
Need aliases ADVANCED Helpful Aliases

Manifest Branch Setup (One-Time)

The z-tools repository needs a manifest branch with the manifest files:

1
2
3
4
5
6
7
8
9
10
11
12

# In z-tools repository
git checkout -b manifest
mkdir -p manifests

# Copy content of manifest-default.xml to manifests/default.xml
# Then:
git add manifests/
git commit -m "chore: add repo tool manifest"
git push origin manifest

# Keep manifest branch independent of main/master
# Only update when project list changes

Groups in Manifest

The manifest defines groups for selective operations:

Group Projects Use Case
python z-edit, z-open repo sync -g python
rust z-kitty-launcher, z-rclone-mount-applete repo sync -g rust
tools All projects except manifests repo sync -g tools
manifests z-tools manifest repo repo sync -g manifests

Key Commands Reference

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Initialization
repo init -u MANIFEST_URL -b BRANCH -m MANIFEST_FILE
repo sync

# Feature development
repo start BRANCH_NAME
repo forall -c git push origin BRANCH_NAME

# Status
repo status
repo branches
repo list

# Operations
repo forall -c COMMAND
repo forall -g GROUP -c COMMAND

# Cleanup
repo prune
repo abandon BRANCH_NAME

Benefits of Repo Tool for Z-Tools

✅ Single checkout - Clone all 4 projects at once ✅ Unified branching - Same branch across all projects ✅ Synchronized releases - Tag and version all projects together ✅ Batch operations - Commit/push across all projects ✅ Group management - Separate python/rust workflows ✅ Team coordination - Everyone works from same manifest ✅ Clear history - Manifest tracks project versions ✅ Simplified CI/CD - Single workflow runs all tests ✅ Better organization - Portfolio feels like single project

Next Steps

  1. Review REPO_TOOL_GUIDE.md for concepts
  2. Follow REPO_TOOL_TUTORIAL.md step-by-step
  3. Create manifest branch in z-tools
  4. Test locally with practice workspace
  5. Train team on basic workflows
  6. Optimize using patterns from REPO_TOOL_ADVANCED.md

Support & Resources

  • Official Repo Tool: https://gerrit.googlesource.com/git-repo
  • Android Setup Guide: https://source.android.com/docs/setup/create/downloading
  • Git Repo Manual: repo help or repo help COMMAND

Summary

This documentation set provides complete implementation guidance for Google repo tool with z-tools:

  • 📖 REPO_TOOL_GUIDE.md: Concepts and reference
  • 🎓 REPO_TOOL_TUTORIAL.md: Step-by-step setup and workflows
  • 🚀 REPO_TOOL_ADVANCED.md: Advanced patterns and optimization
  • 📝 manifest-default.xml: Ready-to-use manifest file

Start with TUTORIAL, refer to GUIDE as needed, and explore ADVANCED for optimization.

Happy multi-project development! 🎉

Updated: