> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Repository Management

> Comprehensive Git repository management with support for branches, tags, LFS, and advanced Git operations

## Overview

Gitea provides full-featured Git repository management that supports all standard Git operations along with advanced features like Git LFS, protected branches, and repository mirroring. Built on native Git functionality, Gitea offers a web-based interface for managing your source code efficiently.

## Repository Creation

<Steps>
  <Step title="Create a New Repository">
    Navigate to the Gitea dashboard and click the "+" icon or "New Repository" button. Repositories can be created under your user account or any organization where you have permissions.

    ```go theme={null}
    // From services/repository/create.go
    func CreateRepository(ctx context.Context, doer *user_model.User, 
                         repo *repo_model.Repository, 
                         opts CreateRepoOptions) error {
        // Repository creation with initialization
        if err := gitrepo.InitRepository(ctx, repo, 
                                        repo.ObjectFormatName); err != nil {
            return err
        }
        return nil
    }
    ```
  </Step>

  <Step title="Initialize with Options">
    Choose repository visibility (public/private), add a README, select a license, and configure a .gitignore template during creation.
  </Step>

  <Step title="Configure Repository Settings">
    After creation, configure additional settings like description, website URL, topics, and default branch.
  </Step>
</Steps>

## Branch Management

### Creating and Managing Branches

Gitea provides comprehensive branch management through both the web interface and Git operations:

```go theme={null}
// From services/repository/branch.go
func CreateNewBranch(ctx context.Context, doer *user_model.User, 
                     repo *repo_model.Repository, 
                     oldBranchName, branchName string) error {
    branch, err := git_model.GetBranch(ctx, repo.ID, oldBranchName)
    if err != nil {
        return err
    }
    return CreateNewBranchFromCommit(ctx, doer, repo, 
                                    branch.CommitID, branchName)
}
```

<Tabs>
  <Tab title="Web UI">
    **Create a Branch**

    1. Navigate to your repository
    2. Click the branch dropdown menu
    3. Type a new branch name
    4. Select the source branch
    5. Click "Create Branch"

    **View Branch List**

    * Access the "Branches" tab to see all branches
    * View commits ahead/behind default branch
    * See branch protection status
    * Access branch deletion options
  </Tab>

  <Tab title="Git CLI">
    ```bash theme={null}
    # Clone repository
    git clone https://gitea.example.com/user/repo.git

    # Create and checkout new branch
    git checkout -b feature-branch

    # Push branch to Gitea
    git push -u origin feature-branch

    # Delete remote branch
    git push origin --delete feature-branch
    ```
  </Tab>
</Tabs>

### Protected Branches

Protect important branches from force pushes and require specific conditions before merging:

<CardGroup cols={2}>
  <Card title="Branch Protection Rules" icon="shield">
    * Require pull request reviews
    * Enforce status checks
    * Restrict who can push
    * Prevent force pushes
    * Require signed commits
  </Card>

  <Card title="Advanced Options" icon="gear">
    * Required approvals count
    * Dismiss stale reviews
    * Required status checks
    * Allowed push users/teams
    * Pattern-based protection
  </Card>
</CardGroup>

<Note>
  Branch protection rules are evaluated based on pattern matching. Use wildcards like `release/*` to protect multiple branches with a single rule.
</Note>

## Tag Management

Tags mark specific points in repository history, typically for releases:

### Creating Tags

<Tabs>
  <Tab title="Web Interface">
    1. Navigate to **Releases** tab
    2. Click **New Release**
    3. Enter tag name (e.g., `v1.0.0`)
    4. Select target branch or commit
    5. Add release notes
    6. Attach binary files if needed
  </Tab>

  <Tab title="Git CLI">
    ```bash theme={null}
    # Create lightweight tag
    git tag v1.0.0

    # Create annotated tag with message
    git tag -a v1.0.0 -m "Release version 1.0.0"

    # Push tags to remote
    git push origin v1.0.0

    # Push all tags
    git push origin --tags
    ```
  </Tab>
</Tabs>

## Git LFS (Large File Storage)

### Overview

Gitea includes built-in support for Git LFS, enabling efficient handling of large binary files:

```go theme={null}
// From services/repository/lfs.go
func GarbageCollectLFSMetaObjects(ctx context.Context, 
                                 opts GarbageCollectLFSMetaObjectsOptions) error {
    if !setting.LFS.StartServer {
        return nil
    }
    return git_model.IterateRepositoryIDsWithLFSMetaObjects(ctx, 
        func(ctx context.Context, repoID, count int64) error {
            repo, err := repo_model.GetRepositoryByID(ctx, repoID)
            if err != nil {
                return err
            }
            return GarbageCollectLFSMetaObjectsForRepo(ctx, repo, opts)
        })
}
```

### Enabling and Using LFS

<Steps>
  <Step title="Enable LFS for Repository">
    Repository administrators can enable LFS in the repository settings under the "Git LFS" section.
  </Step>

  <Step title="Configure Git LFS Client">
    ```bash theme={null}
    # Install Git LFS (if not already installed)
    git lfs install

    # Track large file types
    git lfs track "*.psd"
    git lfs track "*.zip"
    git lfs track "*.mp4"

    # Add .gitattributes
    git add .gitattributes
    ```
  </Step>

  <Step title="Push LFS Files">
    ```bash theme={null}
    # Add and commit large files
    git add large-file.zip
    git commit -m "Add large file"

    # Push to Gitea (LFS files uploaded automatically)
    git push origin main
    ```
  </Step>
</Steps>

<Note>
  LFS objects are stored separately from the Git repository and retrieved on-demand. This keeps repository clones fast even with large files.
</Note>

## Repository Mirroring

### Mirror from External Repository

Gitea can mirror repositories from external sources (GitHub, GitLab, Bitbucket, etc.):

<Accordion title="Configuring Repository Mirrors">
  **Pull Mirroring**

  * Mirror external repositories into Gitea
  * Automatic sync on configurable intervals
  * Supports authentication with tokens/passwords
  * One-way synchronization (external → Gitea)

  **Push Mirroring**

  * Push Gitea repository to external Git hosting
  * Automatic sync on push events
  * Useful for backup and redundancy
  * One-way synchronization (Gitea → external)

  ```go theme={null}
  // From services/mirror/mirror.go
  func SyncPullMirror(ctx context.Context, repoID int64) {
      // Fetch from remote and update local mirror
      repo, err := repo_model.GetRepositoryByID(ctx, repoID)
      if err != nil {
          return
      }
      // Perform sync operation
  }
  ```
</Accordion>

## Repository Templates

Create repository templates to standardize new projects:

<CardGroup cols={2}>
  <Card title="Template Creation" icon="template">
    1. Create a repository with standard structure
    2. Enable "Template Repository" in settings
    3. Others can generate repositories from template
    4. Template includes files, directories, and history
  </Card>

  <Card title="Using Templates" icon="copy">
    1. Click "New Repository"
    2. Select "Repository template" dropdown
    3. Choose from available templates
    4. Customize repository name and settings
  </Card>
</CardGroup>

## Repository Transfer

Transfer repository ownership between users or organizations:

```go theme={null}
// From services/repository/transfer.go
func TransferOwnership(ctx context.Context, doer *user_model.User, 
                      newOwnerName string, repo *repo_model.Repository) error {
    // Transfer repository to new owner
    // Update all related data (issues, PRs, webhooks, etc.)
    return db.WithTx(ctx, func(ctx context.Context) error {
        // Atomic transfer operation
        return performTransfer(ctx, repo, newOwner)
    })
}
```

<Steps>
  <Step title="Initiate Transfer">
    Navigate to **Settings** → **Danger Zone** → **Transfer Repository**
  </Step>

  <Step title="Specify New Owner">
    Enter the username or organization name that will receive the repository
  </Step>

  <Step title="Confirm Transfer">
    The new owner must accept the transfer. All issues, pull requests, and settings are preserved.
  </Step>
</Steps>

## Repository Archive

### Downloading Repository Archives

Download repository snapshots in various formats:

* **ZIP**: Compressed archive of repository contents
* **TAR.GZ**: Compressed tarball for Unix systems
* **Bundle**: Git bundle format with full history

### Archiving Repositories

Archive repositories to make them read-only:

<Note>
  Archived repositories are read-only. No pushes, pull requests, or issues can be created. This is useful for preserving historical projects.
</Note>

## Collaboration Features

<CardGroup cols={2}>
  <Card title="Collaborators" icon="users">
    * Add individual collaborators
    * Assign read, write, or admin permissions
    * Manage access per repository
    * Remove access when needed
  </Card>

  <Card title="Teams (Organizations)" icon="people-group">
    * Assign teams to repositories
    * Team-based permissions
    * Bulk access management
    * Hierarchical organization
  </Card>
</CardGroup>

## Best Practices

<Accordion title="Repository Organization">
  **Naming Conventions**

  * Use descriptive, lowercase names
  * Separate words with hyphens
  * Avoid special characters

  **Branch Strategy**

  * Use `main` or `master` for production
  * Create feature branches for development
  * Use semantic version tags for releases
  * Protect main branches

  **Repository Structure**

  * Include README.md with project description
  * Add LICENSE file for open source
  * Use .gitignore to exclude build artifacts
  * Document contribution guidelines
</Accordion>

## See Also

* [Pull Requests](/features/pull-requests) - Code review and merging workflow
* [Issues](/features/issues) - Bug tracking and project management
* [Actions](/features/actions) - CI/CD automation
* [Wiki](/features/wiki) - Project documentation