headquarter/docs/features/repositories.md

Git Repositories

Overview

Git repositories are managed within projects. You can create bare repositories for new projects or clone existing repositories from remote sources.

How to Use

Creating a Repository

1. Navigate to a project workspace or the Repositories page
2. Click the "New Repository" button
3. Fill in the form:
   • Name: Repository name (required)
   • Remote URL: For cloning (optional)
   • Mirror Clone: Toggle for mirror clones
4. Click "Create Repository"

Bare Repository (No Remote URL)

Creates a new bare git repository. Use this for:

• New projects
• Local-only repositories
• Repositories that will be pushed to later

Clone from Remote

Enter a git URL to clone from:

• https://github.com/user/repo.git
• git@github.com:user/repo.git
• https://gitlab.com/user/repo.git

Smart URL Parsing: If you paste a browser URL (like https://github.com/user/repo/tree/main), the system will automatically suggest the correct git URL.

Mirror Clone

Enable "Mirror Clone" to create a full mirror of a remote repository:

• Clones all branches and tags
• Sets up remote tracking
• Updates can be fetched later

Smart URL Parsing

When pasting URLs, the system automatically detects browser URLs and suggests the correct git clone URL:

Examples:

• https://github.com/user/repo/tree/main → https://github.com/user/repo.git
• https://github.com/user/repo/blob/main/README.md → https://github.com/user/repo.git
• https://gitlab.com/user/repo/-/tree/develop → https://gitlab.com/user/repo.git

You can accept the suggestion or proceed with the original URL.

Viewing Repositories

The Repositories page shows all repositories in a project:

• Repository name
• Clone URL
• Mirror status
• Creation date

Repository Actions

Each repository card provides:

• History: View commit history and branch graph
• Browse: Open in workspace file browser
• Delete: Remove the repository

Deleting a Repository

1. Click the menu icon (⋮) on a repository card
2. Select "Delete"
3. Confirm the deletion

Note: This permanently deletes the repository from disk. This action cannot be undone.

API Reference

Endpoints

• GET /projects/{id}/repositories - List repositories
• POST /projects/{id}/repositories - Create repository
• DELETE /projects/{id}/repositories/{id} - Delete repository
• POST /projects/{id}/repositories/parse-url - Parse and validate URL

See Repositories API for detailed endpoint documentation.

Related Features

• Repository Workspace - Browse repository files
• Git History - View commit history
• Smart Git URL Parsing - Automatic URL correction