gitlab-file

# File Skill Repository file operations for GitLab using `glab api` raw endpoint calls. ## Quick Reference | Operation | Command Pattern | Risk | |-----------|-----------------|:----:| | Get file info | `glab api projects/:id/repository/files/:path?ref=:branch` | - | | Get raw content | `glab api projects/:id/repository/files/:path/raw?ref=:branch` | - | | Get blame | `glab api projects/:id/repository/files/:path/blame?ref=:branch` | - | | Create file | `glab api projects/:id/repository/files/:path -X POST -f ...` | ⚠️ | | Update file | `glab api projects/:id/repository/files/:path -X PUT -f ...` | ⚠️ | | Delete file | `glab api projects/:id/repository/files/:path -X DELETE -f ...` | ⚠️⚠️ | **Risk Legend**: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger ## When to Use This Skill **ALWAYS use when:** - User wants to read file content from GitLab (not local) - User wants to create/update/delete files via GitLab API - User needs file blame information - User wants to download raw file content - User mentions "repository file", "blob", "raw content" **NEVER use when:** - User wants to edit local files (use file editing tools) - User wants to search code (use gitlab-search) - User wants to browse repository tree (use gitlab-repo) - User wants to commit multiple files (use git locally) ## API Prerequisites **Required Token Scopes:** `api` **Permissions:** - Read files: Reporter+ (for private repos) - Create/update/delete files: Developer+ (need push access) ## URL Encoding File paths must be URL-encoded. Slashes in paths become `%2F`: ```bash # src/main.py -> src%2Fmain.py echo 'src/main.py' | jq -Rr @uri # Output: src%2Fmain.py ``` ## Available Commands ### Get File Info (Base64 Encoded) ```bash # Get file metadata and content (base64) glab api "projects/123/repository/files/README.md?ref=main" --method GET # With URL-encoded path glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)?ref=main" # From specific branch glab api "projects/123/repository/files/config.json?ref=develop" --method GET # From tag glab api "projects/123/repository/files/version.txt?ref=v1.0.0" --method GET # From commit SHA glab api "projects/123/repository/files/app.py?ref=abc123" --method GET ``` **Response includes:** - `file_name` - File name - `file_path` - Full path - `size` - File size in bytes - `encoding` - Content encoding (base64) - `content` - Base64-encoded content - `content_sha256` - SHA256 hash - `ref` - Branch/tag/commit - `blob_id` - Blob SHA - `commit_id` - Last commit SHA - `last_commit_id` - Same as commit_id ### Decode Base64 Content ```bash # Get and decode file content glab api "projects/123/repository/files/README.md?ref=main" | \ jq -r '.content' | base64 -d ``` ### Get Raw File Content ```bash # Get raw file content (not base64) glab api "projects/123/repository/files/README.md/raw?ref=main" --method GET # With encoded path glab api "projects/123/repository/files/$(echo 'src/app.py' | jq -Rr @uri)/raw?ref=main" # Binary file (save to file) glab api "projects/123/repository/files/$(echo 'images/logo.png' | jq -Rr @uri)/raw?ref=main" > logo.png ``` ### Get File Blame ```bash # Get blame information glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" --method GET # Parse blame output glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" | \ jq -r '.[] | "\(.commit.author_name): lines \(.lines | length)"' ``` ### Create File ```bash # Create new file with content glab api "projects/123/repository/files/$(echo 'docs/new-file.md' | jq -Rr @uri)" --method POST \ -f branch="main" \ -f content="# New File\n\nContent here" \ -f commit_message="Add new documentation file" # Create with base64 content glab api "projects/123/repository/files/$(echo 'data/config.json' | jq -Rr @uri)" --method POST \ -f branch="main" \ -f content="$(cat config.json | base64)" \ -f encoding="base64" \ -f commit_message="Add configuration file" # Create on new branch glab api "projects/123/repository/files/$(echo 'feature/new.txt' | jq -Rr @uri)" --method POST \ -f branch="feature-branch" \ -f start_branch="main" \ -f content="Feature content" \ -f commit_message="Add feature file" # Create with author info glab api "projects/123/repository/files/script.sh" --method POST \ -f branch="main" \ -f content="#!/bin/bash\necho Hello" \ -f commit_message="Add script" \ -f author_email="dev@example.com" \ -f author_name="Developer" ``` ### Update File ```bash # Update file content glab api "projects/123/repository/files/README.md" --method PUT \ -f branch="main" \ -f content="# Updated README\n\nNew content here" \ -f commit_message="Update README" # Update with base64 (for binary or complex files) glab api "projects/123/repository/files/$(echo 'config/settings.json' | jq -Rr @uri)" --method PUT \ -f branch="main" \ -f content="$(cat settings.json | base64)" \ -f encoding="base64" \ -f commit_message="Update settings" # Update on feature branch glab api "projects/123/repository/files/src%2Fapp.py" --method PUT \ -f branch="feature-update" \ -f content="$(cat app.py | base64)" \ -f encoding="base64" \ -f commit_message="Refactor app module" # Update with last known commit (for conflict detection) glab api "projects/123/repository/files/data.json" --method PUT \ -f branch="main" \ -f content="{ \"updated\": true }" \ -f commit_message="Update data" \ -f last_commit_id="abc123def456" ``` ### Delete File ```bash # Delete file glab api "projects/123/repository/files/$(echo 'old-file.txt' | jq -Rr @uri)" --method DELETE \ -f branch="main" \ -f commit_message="Remove deprecated file" # Delete with author info glab api "projects/123/repository/files/$(echo 'temp/test.txt' | jq -Rr @uri)" --method DELETE \ -f branch="main" \ -f commit_message="Clean up temp files" \ -f author_email="dev@example.com" \ -f author_name="Developer" ``` ## File Operation Options | Option | Type | Description | |--------|------|-------------| | `branch` | string | Target branch (required for write ops) | | `start_branch` | string | Source branch for new files | | `content` | string | File content (plain text or base64) | | `encoding` | string | Content encoding: `text` (default) or `base64` | | `commit_message` | string | Commit message (required for write ops) | | `author_email` | string | Custom author email | | `author_name` | string | Custom author name | | `last_commit_id` | string | Expected last commit (for conflict detection) | ## Common Workflows ### Workflow 1: Download and View File ```bash # Get file content glab api "projects/123/repository/files/$(echo 'config/app.yml' | jq -Rr @uri)/raw?ref=main" ``` ### Workflow 2: Update Configuration File ```bash # 1. Download current file glab api "projects/123/repository/files/config.json/raw?ref=main" > config.json # 2. Edit locally # ... make changes to config.json ... # 3. Upload updated file glab api "projects/123/repository/files/config.json" --method PUT \ -f branch="main" \ -f content="$(cat config.json | base64)" \ -f encoding="base64" \ -f commit_message="Update configuration" ``` ### Workflow 3: Create File on Feature Branch ```bash # Create new file on new branch glab api "projects/123/repository/files/$(echo 'docs/feature.md' | jq -Rr @uri)" --method POST \ -f branch="feature-docs" \ -f start_branch="main" \ -f content="# Feature Documentation\n\nDetails here..." \ -f commit_message="Add feature documentation" ``` ### Workflow 4: Check File History via Blame ```bash # Get blame info for a file glab api "projects/123/repository/files/$(echo 'src/critical.py' | jq -Rr @uri)/blame?ref=main" | \ jq -r '.[] | "\(.commit.short_id) \(.commit.author_name): \(.lines | length) lines"' ``` ### Workflow 5: Batch Read Multiple Files ```bash # Read multiple files for file in "README.md" "package.json" "Dockerfile"; do echo "=== $file ===" glab api "projects/123/repository/files/$(echo "$file" | jq -Rr @uri)/raw?ref=main" echo "" done ``` ### Workflow 6: Copy File Between Branches ```bash # 1. Get file from source branch content=$(glab api "projects/123/repository/files/config.json/raw?ref=develop") # 2. Create/update on target branch echo "$content" | base64 > /tmp/content.b64 glab api "projects/123/repository/files/config.json" --method PUT \ -f branch="main" \ -f content="$(cat /tmp/content.b64)" \ -f encoding="base64" \ -f commit_message="Sync config from develop" ``` ## Troubleshooting | Issue | Cause | Solution | |-------|-------|----------| | 404 Not Found | File doesn't exist | Verify path and branch | | 400 Path encoding | Slashes not encoded | Use `jq -Rr @uri` to encode | | Binary content garbled | Not using base64 | Use `/raw` endpoint or decode base64 | | Conflict on update | File changed | Use `last_commit_id` for optimistic locking | | 403 Forbidden | No push access | Need Developer+ role | | Large file fails | Size limit | GitLab has file size limits | ## Size Limits - Default max file size: 10 MB via API - Large files: Use Git LFS instead - Binary files: Always use base64 encoding ## Best Practices 1. **URL-encode paths**: Always encode file paths with slashes 2. **Use base64 for binary**: Encode binary files as base64 3. **Meaningful commits**: Write descriptive commit messages 4. **Use feature branches**: Don't commit directly to main for big changes 5. **Check for conflicts**: Use `last_commit_id` for critical updates ## Related Documentation - [API Helpers](../shared/docs/API_HELPERS.md) - [Safeguards](../shared/docs/SAFEGUARDS.md) - [Quick Reference](../shared/docs/QUICK_REFERENCE.md) - [GitLab Repository Files API](https://docs.gitlab.com/ee/api/repository_files.html)