# Research: Git Integration Plugin

## Unknowns & Clarifications

1. **Git Library**: Should we use `GitPython` or call `git` CLI directly?
   - **Decision**: Use `GitPython`.
   - **Rationale**: It provides a high-level API for Git operations, making it easier to handle branches, commits, and remotes programmatically compared to parsing CLI output.
   - **Alternatives considered**: `pygit2` (faster but requires libgit2), `subprocess.run(["git", ...])` (simple but brittle).

2. **Git Provider API Integration**: How to handle different providers (GitHub, GitLab, Gitea) for connection testing?
   - **Decision**: Use a unified provider interface with provider-specific implementations.
   - **Rationale**: While Git operations are standard, testing connections and potentially creating repositories might require provider-specific REST APIs.
   - **Alternatives considered**: Generic Git clone test (slower, requires local disk space).

3. **Superset Export/Import**: How to handle the "unpacked" requirement?
   - **Decision**: Use the existing `superset_tool` logic or similar to export as ZIP and then unpack to the Git directory.
   - **Rationale**: Superset's native export is a ZIP. To fulfill FR-019, we must unpack this ZIP into the repository structure.

4. **Merge Conflict UI**: How to implement "Keep Mine/Theirs" in a web UI?
   - **Decision**: Implement a file-based conflict resolver in the Frontend.
   - **Rationale**: Since the data is YAML, we can show a list of conflicting files and let the user pick the version.
   - **Alternatives considered**: Full 3-way merge UI (too complex for MVP).

## Best Practices

- **Security**: Never store PATs in plain text in logs. Use environment variables or encrypted storage if possible (though SQLite is the current project standard).
- **Concurrency**: Git operations on the same repository should be serialized to avoid index locks.
- **Repository Isolation**: Each dashboard gets its own directory/repository to prevent cross-dashboard pollution.

## Findings Consolidations

- **Decision**: Use `GitPython` for core Git logic.
- **Decision**: Use Provider-specific API clients for connection validation.
- **Decision**: Unpack Superset exports into `dashboard/`, `charts/`, `datasets/`, `databases/` directories.