# Git Repository Setup

This guide covers how to configure ComposeSync to work with Git repositories as sources for Docker Compose files.

## Overview

ComposeSync can download Docker Compose files from Git repositories, allowing you to:
- Track specific branches, tags, or commits
- Access files in subdirectories
- Maintain version control for your compose configurations
- Use private repositories (with proper authentication)

## TOML Configuration (Recommended)

The TOML format provides clear and readable Git repository configuration:

```toml
# Git repository configuration
[my-app]
URL = "https://github.com/user/my-app.git"
PATH = "/opt/composesync/stacks/my-app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"

[development-app]
URL = "https://github.com/user/dev-app.git"
PATH = "/opt/composesync/stacks/dev-app"
TOOL = "git"
GIT_SUBPATH = "deploy/docker-compose.yml"
GIT_REF = "develop"
INTERVAL = 1800  # Check every 30 minutes

[stable-release]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/stable"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "v2.1.0"  # Specific tag
INTERVAL = 86400  # Check daily
```

## Legacy .env Configuration

The .env format is supported for backward compatibility:

```env
# Git repository configuration
STACKS=3

STACK_1_NAME=my-app
STACK_1_URL=https://github.com/user/my-app.git
STACK_1_PATH=/opt/composesync/stacks/my-app
STACK_1_TOOL=git
STACK_1_GIT_SUBPATH=docker/docker-compose.yml
STACK_1_GIT_REF=main

STACK_2_NAME=development-app
STACK_2_URL=https://github.com/user/dev-app.git
STACK_2_PATH=/opt/composesync/stacks/dev-app
STACK_2_TOOL=git
STACK_2_GIT_SUBPATH=deploy/docker-compose.yml
STACK_2_GIT_REF=develop
STACK_2_INTERVAL=1800

STACK_3_NAME=stable-release
STACK_3_URL=https://github.com/user/app.git
STACK_3_PATH=/opt/composesync/stacks/stable
STACK_3_TOOL=git
STACK_3_GIT_SUBPATH=docker/docker-compose.yml
STACK_3_GIT_REF=v2.1.0
STACK_3_INTERVAL=86400
```

## Git Configuration Options

### Required Options

| Option | Description | Example |
|--------|-------------|---------|
| `URL` | Git repository URL | `https://github.com/user/repo.git` |
| `PATH` | Local path for the stack | `/opt/composesync/stacks/my-app` |
| `TOOL` | Must be set to `"git"` | `git` |

### Optional Options

| Option | Description | Default | Example |
|--------|-------------|---------|---------|
| `GIT_SUBPATH` | Path to docker-compose.yml in repo | `docker-compose.yml` (root) | `docker/compose.yml` |
| `GIT_REF` | Branch, tag, or commit hash | `main` | `develop`, `v1.2.3`, `abc123` |
| `INTERVAL` | Update interval (seconds) | Global setting | `1800` |
| `KEEP_VERSIONS` | Number of backup versions | Global setting | `5` |

## Git Reference Types

### Branches
```toml
[main-branch]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/main"
TOOL = "git"
GIT_REF = "main"

[feature-branch]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/feature"
TOOL = "git"
GIT_REF = "feature/new-ui"
```

### Tags
```toml
[stable-release]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/stable"
TOOL = "git"
GIT_REF = "v2.1.0"

[beta-release]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/beta"
TOOL = "git"
GIT_REF = "beta-v2.2.0"
```

### Commit Hashes
```toml
[specific-commit]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/commit"
TOOL = "git"
GIT_REF = "abc123def456789"
```

## Subdirectory Configuration

If your Docker Compose file is not in the repository root, use `GIT_SUBPATH`:

```toml
[app-with-subdir]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/app"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
```

Common subdirectory patterns:
- `docker/docker-compose.yml`
- `deploy/docker-compose.yml`
- `compose/docker-compose.yml`
- `infrastructure/docker-compose.yml`

## Multiple Compose Files with Git

For repositories with multiple compose files:

```toml
[complex-app]
URL = "https://github.com/user/complex-app.git"
PATH = "/opt/composesync/stacks/complex"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
EXTRA_FILES_1 = "https://raw.githubusercontent.com/user/complex-app/main/docker/network.yml"
EXTRA_FILES_2 = "https://raw.githubusercontent.com/user/complex-app/main/docker/volumes.yml"
EXTRA_FILES_ORDER = "1,2"
```

## Private Repositories

### SSH Authentication

For private repositories using SSH:

```toml
[private-app]
URL = "git@github.com:user/private-app.git"
PATH = "/opt/composesync/stacks/private"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
```

**Setup SSH keys:**
```bash
# Generate SSH key (if not exists)
ssh-keygen -t ed25519 -C "composesync@your-server"

# Add to SSH agent
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub
```

### HTTPS with Personal Access Token

For private repositories using HTTPS:

```toml
[private-app]
URL = "https://github.com/user/private-app.git"
PATH = "/opt/composesync/stacks/private"
TOOL = "git"
GIT_SUBPATH = "docker/docker-compose.yml"
GIT_REF = "main"
```

**Setup credentials:**
```bash
# Configure Git credentials
git config --global credential.helper store
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

# Test access
git clone https://github.com/user/private-app.git /tmp/test
```

## Best Practices

### 1. Use Semantic Versioning
```toml
[production]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/production"
TOOL = "git"
GIT_REF = "v2.1.0"  # Specific version

[development]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/development"
TOOL = "git"
GIT_REF = "develop"  # Latest development
```

### 2. Organize by Environment
```toml
# Production environments
[prod-app]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/prod"
TOOL = "git"
GIT_REF = "main"
INTERVAL = 7200

# Development environments
[dev-app]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/dev"
TOOL = "git"
GIT_REF = "develop"
INTERVAL = 1800
```

### 3. Use Descriptive Branch Names
```toml
[stable]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/stable"
TOOL = "git"
GIT_REF = "stable"

[experimental]
URL = "https://github.com/user/app.git"
PATH = "/opt/composesync/stacks/experimental"
TOOL = "git"
GIT_REF = "experimental"
```

## Troubleshooting

### Repository Not Found
```bash
# Test repository access
git clone https://github.com/user/repo.git /tmp/test

# Check SSH access
ssh -T git@github.com
```

### Branch/Tag Not Found
```bash
# List available branches
git ls-remote --heads https://github.com/user/repo.git

# List available tags
git ls-remote --tags https://github.com/user/repo.git
```

### Subpath Not Found
```bash
# Check if file exists in repository
git ls-tree -r --name-only HEAD | grep docker-compose.yml
```

### Authentication Issues
```bash
# Test SSH connection
ssh -T git@github.com

# Test HTTPS with token
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
```

## Monitoring Git Operations

### View Git Operations in Logs
```bash
# View ComposeSync logs
sudo journalctl -u composesync -f

# Filter for Git operations
sudo journalctl -u composesync | grep "git"
```

### Check Repository Status
```bash
# Check if repository is cloned
ls -la /opt/composesync/stacks/my-app/.git

# Check current branch/commit
git -C /opt/composesync/stacks/my-app/.git rev-parse --abbrev-ref HEAD
git -C /opt/composesync/stacks/my-app/.git rev-parse HEAD
```

### Manual Git Operations
```bash
# Manually fetch updates
cd /opt/composesync/stacks/my-app/.git
git fetch origin

# Check available branches
git branch -r

# Switch to different branch
git checkout develop
```