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)
   • Owner and Repository: For SSH cloning from git.commumedia.org
   • 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 the repository owner and name to clone from git.commumedia.org over SSH:

• owner: alice
• repository: demo
• Resulting SSH URL: git@git.commumedia.org:alice/demo.git

Advanced fallback: If needed, you can still paste a full git URL and the system will suggest the correct clone 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