headquarter/docs/features/workspace.md

Repository Workspace

Overview

The Repository Workspace is the default view when you open a project. It provides a file browser and viewer for exploring repository contents, similar to GitHub or GitLab's file browser.

How to Use

Workspace Layout

┌─────────────────────────────────────────────┐
│  [Repo Selector ▼] [Branch Selector ▼]       │
├─────────────────┬───────────────────────────┤
│  File Tree      │  Main Content             │
│                 │                           │
│  📁 src/        │  Breadcrumbs: src > main  │
│  📁 tests/      │                           │
│  📄 README.md   │  [Edit] [History]         │
│  📄 .gitignore  │                           │
│                 │  File content here...     │
│                 │                           │
└─────────────────┴───────────────────────────┘

Repository Selection

If a project has multiple repositories:

1. Use the Repository Selector dropdown at the top
2. Choose the repository you want to browse
3. The file tree updates automatically

Branch Selection

1. Use the Branch Selector dropdown
2. Select a branch from the list
3. The file tree refreshes to show that branch's contents

Browsing Files

Navigate directories:

• Click on a folder (📁) to expand it
• Click again to collapse
• The file tree shows the full directory structure

View file contents:

• Click on a file (📄) to open it
• The file viewer shows:
  • File path breadcrumbs
  • File content with syntax highlighting
  • File metadata (size, last commit)

File Viewer

The file viewer supports:

• Syntax highlighting for common languages
• Line numbers
• Breadcrumb navigation (click any path segment)

Quick Editing

For small changes:

1. Open a file in the viewer
2. Click the "Edit" button
3. Make your changes in the text area
4. Enter a commit message
5. Click "Save"

The system will:

• Commit the changes to the current branch
• Show the new commit hash
• Refresh the file view

Note: This creates a real git commit. Make sure your commit message describes the change.

Binary Files

Binary files (images, compiled code, etc.) cannot be viewed or edited in the workspace. The viewer will show "Binary file - cannot display."

Keyboard Navigation

• Click folder to expand/collapse
• Click file to view
• Click breadcrumb to navigate up

API Reference

Endpoints

• GET /projects/{id}/repositories/{id}/files - List files in directory
• GET /projects/{id}/repositories/{id}/files/content - Get file content
• POST /projects/{id}/repositories/{id}/files/content - Update file
• GET /projects/{id}/repositories/{id}/branches - List branches

See Repositories API for detailed endpoint documentation.

Related Features

• Git Repositories - Manage repositories
• Git History - View commit history