### Website Development Setup (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Guides through setting up the Next.js frontend for local development. Includes steps for navigating to the directory, creating and configuring the environment file, installing dependencies with Bun, and running development or production builds.

```bash
# Navigate to website directory
cd website

# Create environment file
cp .env.local.example .env.local

# Edit .env.local with your configuration:
# REDIS_HOST=localhost
# REDIS_PORT=6379
# REDIS_PASSWORD=your_redis_password
# SECRET_KEY=your_secret_key
# API_URL=http://localhost:8081

# Install dependencies with Bun
bun install

# Run development server
bun dev

# Build for production
bun run build

# Start production server
bun start

```

--------------------------------

### Copy Environment File (Website)

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Copies the example environment file to '.env.local' for the website. This file is used to configure website-specific settings and credentials.

```bash
cp .env.local.example .env.local
```

--------------------------------

### Install Website Dependencies with Bun

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Installs the necessary Node.js packages for the Gitmotion website using the Bun package manager. This command ensures all required libraries are available.

```bash
bun install
```

--------------------------------

### Docker Environment Setup and Commands (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Provides instructions for setting up the environment variables in a `.env` file and commands to build, run, and view logs for the Dockerized Gitmotion application.

```bash
# Environment setup (.env file)
API_PORT=8081
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_secure_redis_password
SECRET_KEY=your_secret_key_for_token_encryption

# Build and run
docker compose build
docker compose up -d

# View logs
docker compose logs -f gitmotion-api

```

--------------------------------

### Run Gitmotion Website with Bun

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Starts the development server for the Gitmotion website using the Bun runtime. This command compiles and serves the website for local development.

```bash
bun dev
```

--------------------------------

### Copy Environment File (API)

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Copies the example environment file to a new file named '.env' for the API. This file should then be filled with the necessary credentials.

```bash
cp .env.example .env
```

--------------------------------

### POST /api/gource/start

Source: https://context7.com/3eif/gitmotion/llms.txt

Starts a new Gource visualization job. This endpoint acts as a frontend proxy, handling token encryption and rate limiting before forwarding requests to the Rust API.

```APIDOC
## POST /api/gource/start

### Description
Starts a new Gource visualization job. This endpoint acts as a frontend proxy, handling token encryption and rate limiting before forwarding requests to the Rust API.

### Method
POST

### Endpoint
/api/gource/start

### Parameters
#### Request Body
- **repo_url** (string) - Required - The URL of the Git repository.
- **access_token** (string) - Optional - The access token for private repositories.
- **settings** (object) - Optional - Configuration for the Gource visualization.
  - **show_file_extension_key** (boolean) - Optional - Show color legend for file types. Defaults to false.
  - **show_usernames** (boolean) - Optional - Display contributor names. Defaults to true.
  - **show_dirnames** (boolean) - Optional - Display directory names. Defaults to true.
  - **dir_font_size** (number) - Optional - Font size for directories (1-20). Defaults to 11.
  - **file_font_size** (number) - Optional - Font size for files (1-20). Defaults to 10.
  - **user_font_size** (number) - Optional - Font size for usernames (1-20). Defaults to 12.

### Request Example
```json
{
  "repo_url": "https://github.com/user/repo.git",
  "access_token": "your_github_token",
  "settings": {
    "show_file_extension_key": false,
    "show_usernames": true,
    "show_dirnames": true,
    "dir_font_size": 11,
    "file_font_size": 10,
    "user_font_size": 12
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string) - A UUID for tracking the job status.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

#### Error Response (429)
- **error** (string) - Error message, e.g., "Rate limit exceeded."
```

--------------------------------

### GET /health

Source: https://context7.com/3eif/gitmotion/llms.txt

Simple health check endpoint to verify the API server is running.

```APIDOC
## GET /health

### Description
Simple health check endpoint to verify the API server is running.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the health of the API server (e.g., "healthy").

#### Response Example
```json
{
  "status": "healthy"
}
```
```

--------------------------------

### Run Docker Container for API

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Starts the Gitmotion API service using Docker Compose. This command launches the container and makes the API accessible.

```bash
docker compose up
```

--------------------------------

### GET /video/{job_id}

Source: https://context7.com/3eif/gitmotion/llms.txt

Retrieves the generated MP4 video file for a completed job. Returns 404 if the video doesn't exist or has expired.

```APIDOC
## GET /video/{job_id}

### Description
Retrieves the generated MP4 video file for a completed job. Returns 404 if the video doesn't exist or has expired.

### Method
GET

### Endpoint
/video/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job whose video to download.

### Response
#### Success Response (200)
The MP4 video file for the specified job.

#### Response Example
(Binary content of the MP4 file)

# The video is saved as: gource_550e8400-e29b-41d4-a716-446655440000.mp4
```

--------------------------------

### Start Gource Job API Request (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Initiates a Gource visualization job for a given Git repository URL. Supports public and private repositories (with encrypted tokens) and custom visualization settings. Returns a job ID for tracking.

```bash
curl -X POST http://localhost:8081/start-gource \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/facebook/react"
  }'

# Response:
# {"job_id": "550e8400-e29b-41d4-a716-446655440000"}

# Start a job with custom visualization settings
curl -X POST http://localhost:8081/start-gource \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/facebook/react",
    "settings": {
      "show_file_extension_key": true,
      "show_usernames": true,
      "show_dirnames": true,
      "dir_font_size": 14,
      "file_font_size": 12,
      "user_font_size": 16
    }
  }'

# For private GitHub repositories (token must be encrypted by the frontend)
curl -X POST http://localhost:8081/start-gource \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/username/private-repo",
    "access_token": "iv_hex:encrypted_token_hex"
  }'
```

--------------------------------

### Start Gource Visualization (TypeScript)

Source: https://context7.com/3eif/gitmotion/llms.txt

Initiates a Gource visualization job by sending repository URL and optional access token to the backend API. Handles token encryption and rate limiting. Returns a job ID for tracking. Requires a fetch implementation.

```typescript
async function startVisualization(repoUrl: string, accessToken?: string) {
  const response = await fetch("/api/gource/start", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      repo_url: repoUrl,
      access_token: accessToken, // Will be encrypted before forwarding
      settings: {
        show_file_extension_key: false,
        show_usernames: true,
        show_dirnames: true,
        dir_font_size: 11,
        file_font_size: 10,
        user_font_size: 12,
      },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    // Handle rate limit (429) or other errors
    throw new Error(error.error);
  }

  const data = await response.json();
  return data.job_id; // UUID for tracking the job
}
```

--------------------------------

### GET /api/gource/status/{jobId}

Source: https://context7.com/3eif/gitmotion/llms.txt

Polls the status of a Gource visualization job. This endpoint is designed to be used with SWR for automatic revalidation until the video is ready.

```APIDOC
## GET /api/gource/status/{jobId}

### Description
Polls the status of a Gource visualization job. This endpoint is designed to be used with SWR for automatic revalidation until the video is ready.

### Method
GET

### Endpoint
/api/gource/status/`jobId`

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The UUID of the job to poll.

### Response
#### Success Response (200)
- **step** (string) - The current progress step of the job (e.g., InitializingProject, AnalyzingHistory, GeneratingVisualization).
- **video_url** (string | null) - The URL of the generated video if the job is complete, otherwise null.
- **repo_url** (string) - The URL of the repository being processed.
- **error** (string | null) - An error message if the job failed, otherwise null.
- **settings** (object) - The Gource settings used for this job.

#### Response Example
```json
{
  "step": "GeneratingVisualization",
  "video_url": null,
  "repo_url": "https://github.com/user/repo.git",
  "error": null,
  "settings": {
    "show_file_extension_key": false,
    "show_usernames": true,
    "show_dirnames": true,
    "dir_font_size": 11,
    "file_font_size": 10,
    "user_font_size": 12
  }
}
```
```

--------------------------------

### GET /job-status/{job_id}

Source: https://context7.com/3eif/gitmotion/llms.txt

Retrieves the current status of a visualization job including progress step, video URL when complete, or error message if failed.

```APIDOC
## GET /job-status/{job_id}

### Description
Retrieves the current status of a visualization job including progress step, video URL when complete, or error message if failed.

### Method
GET

### Endpoint
/job-status/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job to check.

### Response
#### Success Response (200)
- **step** (integer) - The current progress step of the job (1: Initializing, 2: Analyzing, 3: Generating).
- **video_url** (string) - The URL of the generated video if the job is complete, otherwise null.
- **repo_url** (string) - The URL of the repository being processed.
- **error** (string) - An error message if the job failed, otherwise null.
- **settings** (object) - The visualization settings used for the job.

#### Response Example (In Progress)
```json
{
  "step": 2,
  "video_url": null,
  "repo_url": "https://github.com/facebook/react",
  "error": null,
  "settings": {
    "show_file_extension_key": false,
    "show_usernames": true,
    "show_dirnames": true,
    "dir_font_size": 11,
    "file_font_size": 10,
    "user_font_size": 12
  }
}
```

#### Response Example (Complete)
```json
{
  "step": 3,
  "video_url": "/gource_videos/gource_550e8400-e29b-41d4-a716-446655440000.mp4",
  "repo_url": "https://github.com/facebook/react",
  "error": null,
  "settings": {...}
}
```
```

--------------------------------

### Docker Compose Configuration (YAML)

Source: https://context7.com/3eif/gitmotion/llms.txt

Defines the Docker Compose setup for running the Gitmotion API server alongside a Redis instance. Includes service definitions, port mappings, volumes, and environment variables for configuration.

```yaml
# docker-compose.yml
services:
  gitmotion-api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "${API_PORT:-8081}:8081"
    volumes:
      - ./gource_videos:/gource_videos
    depends_on:
      - redis
    environment:
      - REDIS_URL=redis://redis:${REDIS_PORT:-6379}
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - SECRET_KEY=${SECRET_KEY}

  redis:
    image: "redis:alpine"
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redis_data:/data

volumes:
  gource_videos:
  redis_data:

```

--------------------------------

### Get Job Status API Request (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Retrieves the status of a Gource visualization job using its ID. Provides progress, video URL upon completion, or error information. Supports checking jobs in progress or completed states.

```bash
curl http://localhost:8081/job-status/550e8400-e29b-41d4-a716-446655440000

# Response when in progress:
# {
#   "step": 2,
#   "video_url": null,
#   "repo_url": "https://github.com/facebook/react",
#   "error": null,
#   "settings": {
#     "show_file_extension_key": false,
#     "show_usernames": true,
#     "show_dirnames": true,
#     "dir_font_size": 11,
#     "file_font_size": 10,
#     "user_font_size": 12
#   }
# }

# Response when complete:
# {
#   "step": 3,
#   "video_url": "/gource_videos/gource_550e8400-e29b-41d4-a716-446655440000.mp4",
#   "repo_url": "https://github.com/facebook/react",
#   "error": null,
#   "settings": {...}
# }

# Progress steps:
# 1 = InitializingProject (cloning repository)
# 2 = AnalyzingHistory (counting commits and days)
# 3 = GeneratingVisualization (rendering video)
```

--------------------------------

### POST /start-gource

Source: https://context7.com/3eif/gitmotion/llms.txt

Initiates a new Gource visualization job for a given repository. Returns a job ID for tracking progress. Rate-limited to 10 requests per 6 hours per IP address.

```APIDOC
## POST /start-gource

### Description
Initiates a new Gource visualization job for a given repository. Returns a job ID for tracking progress. Rate-limited to 10 requests per 6 hours per IP address.

### Method
POST

### Endpoint
/start-gource

### Parameters
#### Request Body
- **repo_url** (string) - Required - The URL of the Git repository to visualize.
- **access_token** (string) - Optional - An encrypted access token for private repositories.
- **settings** (object) - Optional - Custom visualization settings.
  - **show_file_extension_key** (boolean) - Optional - Whether to show file extension keys.
  - **show_usernames** (boolean) - Optional - Whether to show usernames.
  - **show_dirnames** (boolean) - Optional - Whether to show directory names.
  - **dir_font_size** (integer) - Optional - Font size for directory names.
  - **file_font_size** (integer) - Optional - Font size for file names.
  - **user_font_size** (integer) - Optional - Font size for usernames.

### Request Example
```json
{
  "repo_url": "https://github.com/facebook/react",
  "settings": {
    "show_file_extension_key": true,
    "show_usernames": true,
    "show_dirnames": true,
    "dir_font_size": 14,
    "file_font_size": 12,
    "user_font_size": 16
  }
}
```

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the Gource job.

#### Response Example
```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
```

--------------------------------

### Clone Gitmotion Repository

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Clones the Gitmotion repository from GitHub and navigates into the project directory. This is the first step to setting up the project locally.

```bash
git clone https://github.com/3eif/gitmotion.git
cd gitmotion
```

--------------------------------

### GourceSettings Configuration

Source: https://context7.com/3eif/gitmotion/llms.txt

Details on the GourceSettings object, which allows customization of the visualization's appearance.

```APIDOC
## GourceSettings Configuration

### Description
The `GourceSettings` object controls the appearance and behavior of the Gource visualization. These settings can be customized when starting a new visualization job.

### Fields
- **show_file_extension_key** (boolean) - Show color legend for file types. Defaults to `false`.
- **show_usernames** (boolean) - Display contributor names. Defaults to `true`.
- **show_dirnames** (boolean) - Display directory names. Defaults to `true`.
- **dir_font_size** (number) - Font size for directory names. Accepts values from 1 to 20. Defaults to `11`.
- **file_font_size** (number) - Font size for file names. Accepts values from 1 to 20. Defaults to `10`.
- **user_font_size** (number) - Font size for usernames. Accepts values from 1 to 20. Defaults to `12`.

### Default Settings Example
```typescript
interface GourceSettings {
  show_file_extension_key: boolean;
  show_usernames: boolean;
  show_dirnames: boolean;
  dir_font_size: number;
  file_font_size: number;
  user_font_size: number;
}

const defaultSettings: GourceSettings = {
  show_file_extension_key: false,
  show_usernames: true,
  show_dirnames: true,
  dir_font_size: 11,
  file_font_size: 10,
  user_font_size: 12,
};
```
```

--------------------------------

### Download Video API Request (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Downloads the generated MP4 Gource visualization video for a completed job. Requires the job ID and will return a 404 error if the video is not found or has expired.

```bash
# Download the generated video
curl -O http://localhost:8081/video/550e8400-e29b-41d4-a716-446655440000

# The video is saved as: gource_550e8400-e29b-41d4-a716-446655440000.mp4
```

--------------------------------

### GourceSettings Interface and Defaults (TypeScript)

Source: https://context7.com/3eif/gitmotion/llms.txt

Defines the TypeScript interface for Gource visualization settings, controlling aspects like font sizes and visibility of elements. Provides default settings for common configurations.

```typescript
interface GourceSettings {
  show_file_extension_key: boolean; // Show color legend for file types
  show_usernames: boolean;          // Display contributor names
  show_dirnames: boolean;           // Display directory names
  dir_font_size: number;            // Font size for directories (1-20)
  file_font_size: number;           // Font size for files (1-20)
  user_font_size: number;           // Font size for usernames (1-20)
}

// Default settings
const defaultSettings: GourceSettings = {
  show_file_extension_key: false,
  show_usernames: true,
  show_dirnames: true,
  dir_font_size: 11,
  file_font_size: 10,
  user_font_size: 12,
};

```

--------------------------------

### Build Docker Image for API

Source: https://github.com/3eif/gitmotion/blob/main/README.md

Builds the Docker image for the Gitmotion API using Docker Compose. This command prepares the containerized environment for the API.

```bash
docker compose build
```

--------------------------------

### POST /stop/{job_id}

Source: https://context7.com/3eif/gitmotion/llms.txt

Stops a running visualization job. Only works on jobs that haven't completed or errored yet.

```APIDOC
## POST /stop/{job_id}

### Description
Stops a running visualization job. Only works on jobs that haven't completed or errored yet.

### Method
POST

### Endpoint
/stop/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job to stop.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the job was stopped.
- **status** (string) - The status of the operation (e.g., "stopped").

#### Response Example (Success)
```json
{
  "message": "Job stopped successfully and temporary files cleaned up",
  "status": "stopped"
}
```

#### Response Example (Job Already Completed)
```json
{
  "error": "Cannot stop job: already completed or errored",
  "status": "unchanged"
}
```
```

--------------------------------

### Poll Job Status with SWR (TypeScript)

Source: https://context7.com/3eif/gitmotion/llms.txt

Polls the status of a Gource visualization job using the SWR library for automatic revalidation. Configured to poll every 5 seconds and disable revalidation on focus. Handles job completion or failure states.

```typescript
import useSWR from "swr";

interface JobStatus {
  step: ProgressStep;
  video_url: string | null;
  repo_url: string;
  error: string | null;
  settings: GourceSettings;
}

enum ProgressStep {
  InitializingProject = 1,
  AnalyzingHistory = 2,
  GeneratingVisualization = 3,
}

// Polling job status with SWR
const { data: jobStatus, error } = useSWR<JobStatus>(
  jobId ? `/api/gource/status/${jobId}` : null,
  fetcher,
  {
    refreshInterval: 5000, // Poll every 5 seconds
    revalidateOnFocus: false,
  }
);

// Check completion
if (jobStatus?.video_url) {
  // Video is ready at: /api/gource/video/${jobId}
}
if (jobStatus?.error) {
  // Job failed with error message
}
```

--------------------------------

### Stop Job API Request (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Stops a running Gource visualization job using its ID. This action is only effective on jobs that have not yet completed or encountered an error. It also cleans up temporary files associated with the job.

```bash
# Stop a running job
curl http://localhost:8081/stop/550e8400-e29b-41d4-a716-446655440000

# Response on success:
# {"message": "Job stopped successfully and temporary files cleaned up", "status": "stopped"}

# Response if job already completed:
# {"error": "Cannot stop job: already completed or errored", "status": "unchanged"}
```

--------------------------------

### Health Check API Request (Bash)

Source: https://context7.com/3eif/gitmotion/llms.txt

Performs a simple health check on the Gitmotion API server. Returns a JSON response indicating the server's operational status.

```bash
curl http://localhost:8081/health

# Response:
# {"status": "healthy"}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.