Gitea-Workflow/gitea-git-clone/README.md

# Gitea Workflow

A Visual Studio Code extension that allows you to manage your Gitea repositories directly from your workspace. Clone repositories via SSH, handle authentication with Personal Access Tokens (PAT's), create and view Pull Requests (PRs), manage multiple Gitea instances, and view branch and build statuses—all within VSCode.

## Features

- **Gitea Authentication**: Authenticate with one or multiple Gitea instances using Personal Access Tokens.
- **Multiple Gitea Instances**: Manage and switch between multiple Gitea instances within VSCode.
- **Clone via SSH**: Clone repositories from Gitea using SSH URLs.
- **Auto-Open Repository**: After cloning, the repository will be automatically opened in the workspace.
- **See Open Pull Requests**: Use the icon in the status bar or the command to check how many open PRs exist and open them in a browser.
- **Create Pull Requests**: Create Pull Requests (PRs) directly from your workspace.
- **Enhanced Status Bar Integration**: View the current branch status and build status directly from the VSCode status bar.

## Commands

- `Gitea: Authenticate` → Authenticate with a selected Gitea instance using your Personal Access Token (PAT).
- `Gitea: Configure` → Add, edit, or remove Gitea instances and their PAT's.
- `Gitea: Clone Repository` → Clone a repository from a selected Gitea instance via SSH.
- `Gitea: Create Pull Request` → Create a pull request for the current repository.
- `Gitea: Show Open Pull Requests` → Show open pull requests for the current repository and link to them.
- `Gitea: Create Repository` → Create a new repository in a selected Gitea instance.

## Requirements

- A Gitea instance with SSH access.
- A Personal Access Token (PAT) from your Gitea instance(s) with necessary permissions (e.g., `repo`, `admin:org`).

## Configuration

You can configure multiple Gitea instances and their Personal Access Tokens in your VSCode settings:

```json
{
  "gitea.instances": [
    {
      "name": "Gitea Instance 1",
      "url": "https://gitea.instance1.com",
      "token": "your-personal-access-token-1"
    },
    {
      "name": "Gitea Instance 2",
      "url": "https://gitea.instance2.com",
      "token": "your-personal-access-token-2"
    }
  ]
}
````

Alternatively, you can use the `Gitea: Configure` command to add or edit instances interactively.

## Usage

### Authentication

Run `Gitea: Authenticate` to authenticate with one of your configured Gitea instances.

You can set up or update your Gitea instances and Personal Access Tokens by running `Gitea: Configure`.

### Managing Multiple Gitea Instances

Use `Gitea: Configure` to add, edit, or remove Gitea instances.  
When executing commands like cloning a repository or creating a pull request,  
you'll be prompted to select the Gitea instance you want to use if applicable.

### Cloning a Repository

Run `Gitea: Clone Repository` from the command palette.  
Select the Gitea instance from which you want to clone.  
Choose the repository you want to clone.  
Select the folder where you want to clone the repository.  
The repository will be cloned via SSH and automatically opened in a new VSCode window.  

### Creating a Repository

Run `Gitea: Create Repository` from the command palette.  
Select the Gitea instance where you want to create the repository.  
Choose the owner (your personal account or an organization you belong to).  
Enter the name of the new repository.  
The repository name will be sanitized and formatted to meet Gitea's requirements.  
Select the visibility of the repository (Private or Public).  
The repository will be created with an MIT license and initialized with a `.gitignore` template for Visual Studio Code.  
After creation, the repository will be cloned, and you can start working immediately.  

### Creating a Pull Request

    Ensure that you are on the branch for which you want to create a Pull Request.

Run `Gitea: Create Pull Request` from the command palette.  
The PR title will be automatically set to the latest commit message, and the body will include the commit description (if any).  
The current branch will be used as the source (head), and the base branch will be automatically fetched from the repository's default branch (e.g., main or master).  
Once the Pull Request is created, the Gitea web interface will open in your browser for further review.  

### Viewing Open Pull Requests

The status bar will display the number of open pull requests for the current repository.  
Click on the PR count in the status bar or run `Gitea: Show Open Pull` Requests to view and open them in a browser.

### Enhanced Status Bar Integration

**Branch Status**: The status bar shows the current branch and its status relative to the remote branch (e.g., ahead, behind).  
**Build Status**: The build status of the current commit is displayed in the status bar (e.g., success, failure, pending).  

### Issues

If you encounter any issues or have feature requests, please feel free to submit them in the [issues section](https://gitea.computerliebe.org/ComputerLiebe/Gitea-Workflow/issues)