# Using Git Repositories in Config Profiles

## Overview

Config profiles now support mounting files and directories from git repositories directly into your tool instances. This is useful for:

- Sharing configuration files across multiple instances
- Mounting dotfiles or development environment configs
- Including shared code or assets from other repositories
- Pinning specific branches or versions of dependencies

## How It Works

When you start a tool instance with a config profile that has git mounts:

1. The system checks if the repository is cloned locally
2. If not cloned and a remote URL is available, it automatically clones the repository
3. If a branch is specified, it checks out that branch
4. Files matching the source path pattern are mounted as bind mounts into the container
5. Instance startup continues normally

## Adding Git Mounts

### Step 1: Select a Repository

In the config profile editor, find the "Git Mounts" section. Choose a repository from the dropdown. Only repositories from your projects are available.

### Step 2: Configure Source Path

The source path determines which files from the repository to mount:

- **`.`** (default): Mount the entire repository
- **`configs/`**: Mount the configs directory
- **`*.json`**: Mount all JSON files in the repository root
- **`src/**/*.py`**: Mount all Python files in the src directory recursively

**Glob patterns are supported** - use `*` for any characters, `**` for recursive matching.

### Step 3: Set Target Path

The target path is where files appear inside the container:

- `/app/config` - Mount to /app/config
- `/home/user/dotfiles` - Mount to user's home directory
- `/workspace/shared` - Mount to workspace shared folder

Target paths must be absolute (start with `/`).

### Step 4: Optional Branch Selection

You can pin a specific branch or tag:

- `main` - Use the main branch
- `develop` - Use the develop branch
- `v1.2.3` - Pin to a specific tag

If not specified, the current checked-out branch is used.

## Examples

### Dotfiles Configuration

Mount your dotfiles repository into the home directory:

```
Repository: dotfiles
Source Path: .
Target Path: /home/user
Branch: main
```

### Shared Configuration Files

Mount only JSON config files from a shared config repo:

```
Repository: shared-configs
Source Path: *.json
Target Path: /app/config
Branch: production
```

### Development Tools Configuration

Mount specific tool configs:

```
Repository: dev-tools
Source Path: vscode/
Target Path: /workspace/.vscode
```

### Multiple Mounts

You can add multiple git mounts to a single profile:

1. Dotfiles → `/home/user`
2. Shared configs → `/app/config`
3. Assets → `/app/static`

## Profile Includes

Git mounts work with profile includes. If Profile A includes Profile B:

- Both profiles' git mounts are merged
- Same repository + target path combinations override (later profile wins)
- Different combinations are kept

Example:
```
Base Profile:
  - repo: dotfiles, target: /home/user, branch: main

Development Profile (includes Base):
  - repo: dotfiles, target: /home/user, branch: develop
  - repo: dev-tools, target: /opt/tools

Resolved Result:
  - repo: dotfiles, target: /home/user, branch: develop  (overridden)
  - repo: dev-tools, target: /opt/tools                   (added)
```

## Error Handling

Git mounts are non-blocking:

- **Repository not found**: Mount is skipped, instance continues starting
- **Clone fails**: Mount is skipped, warning logged
- **Branch doesn't exist**: Falls back to current branch, warning logged
- **Glob pattern matches nothing**: Mount is skipped, warning logged
- **Path outside repository**: Match is skipped, warning logged

You can check the instance logs to see which mounts succeeded and which failed.

## Best Practices

1. **Use specific paths**: Instead of mounting the entire repository, mount only the files you need. This reduces startup time and avoids conflicts.

2. **Pin branches**: For reproducible environments, pin specific branches or tags rather than using the default branch.

3. **Keep repositories small**: Large repositories take longer to clone. Consider splitting config repositories from code repositories.

4. **Use absolute target paths**: Always use absolute paths (starting with `/`) for target paths to ensure files end up in the expected location.

5. **Test includes**: When using profile includes, use the Preview feature to verify that git mounts are merged as expected.

## Troubleshooting

**Issue**: Git mount not appearing in container
**Solution**: Check instance logs for warnings. Common causes: repository not found, clone failure, or source path not matching any files.

**Issue**: Wrong branch mounted
**Solution**: Verify branch name is correct. If branch doesn't exist locally, the system falls back to the current branch. Ensure the remote has the branch.

**Issue**: Too many files matched
**Solution**: Use more specific glob patterns. The system limits matches to 100 files per glob pattern.

**Issue**: Permission denied
**Solution**: Ensure the target path inside the container is writable. Some paths like `/usr` or `/etc` may require root access.