Document

Baedal - Git Repository File/Folder Fetcher

Project Overview

A CLI tool and npm library for selectively downloading specific files or folders from Git repositories.

Project Name: baedal (배달 - Korean word for "deliver")

Core Objectives

Overcome limitations of existing tools (degit, giget, github-files-fetcher) by supporting:

• ✅ Single file download
• ✅ Folder download
• ✅ Automatic default branch detection
• ✅ Short URL syntax (user/repo/path)
• ✅ Private repository access

Tech Stack

Language

• TypeScript (Core implementation)
• Node.js (Runtime)

Key Dependencies

{
  "dependencies": {
    "commander": "^12.0.0",
    "ofetch": "^1.3.0",
    "tar-fs": "^3.0.0",
    "picocolors": "^1.0.0",
    "globby": "^14.0.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "tsup": "^8.0.0",
    "vitest": "^1.0.0",
    "@types/node": "^20.0.0",
    "@types/tar-fs": "^2.0.0"
  }
}

Build Tool

• tsup - Zero-config TypeScript bundler
  • ESM + CJS dual output
  • Type declarations auto-generation
  • Fast builds

Supported Platforms

Phase 1 (MVP)

1. GitHub
2. GitLab
3. Bitbucket

Core Features

1. URL Parsing

Support various URL formats:

user/repo/path/file.md           # Short form (GitHub default)
user/repo#branch/path/file.md    # With branch
gh:user/repo/path                # GitHub explicit
gitlab:user/repo/path            # GitLab
bitbucket:user/repo/path         # Bitbucket
https://github.com/user/repo/blob/main/file.md  # Full URL

2. Automatic Default Branch Detection

Auto-detect default branch via platform APIs when branch is omitted:

• GitHub API: /repos/{owner}/{repo} → default_branch
• GitLab API: /api/v4/projects/{id} → default_branch
• Bitbucket API: /2.0/repositories/{owner}/{repo} → mainbranch

3. File/Folder Download

• File: Direct download via raw URL
• Folder: Download as tarball, extract specific path

4. File Filtering

• Exclude specific files/folders (glob patterns)
• .gitignore style pattern support

5. Private Repository Support

Platform-specific authentication:

• GitHub: Personal Access Token (Authorization: token {token})
• GitLab: Private Token (PRIVATE-TOKEN: {token})
• Bitbucket: Basic Auth

Authentication methods:

• CLI option (--auth)
• Environment variables (BAEDAL_AUTH, GITHUB_TOKEN, etc.)
• Config file (~/.baedalrc)

CLI Interface

Basic Usage

# Download file
baedal user/repo/path/file.md

# Download folder
baedal user/repo/path/folder

# Specify branch
baedal user/repo#dev/path/file.md

# Specify output directory
baedal user/repo/file.md -o ./output

# Private repository
baedal user/repo/file.md --auth YOUR_TOKEN

# GitLab/Bitbucket
baedal gitlab:user/repo/file.md
baedal bitbucket:user/repo/folder

Options

-o, --out <PATH>        Output directory
--auth <TOKEN>          Authentication token
--exclude <PATTERN>     File pattern to exclude
--branch <BRANCH>       Branch name (instead of auto-detect)
--force                 Overwrite existing files
--dry-run              Simulate without actual download

Programmatic API

import { fetchFile, fetchFolder } from 'baedal';

// Download file
await fetchFile('user/repo/path/file.md', {
  out: './output',
  auth: process.env.GITHUB_TOKEN
});

// Download folder
await fetchFolder('user/repo/path/folder', {
  out: './output',
  exclude: ['**/*.test.js', 'node_modules/**']
});

Development Phases

Phase 1 - MVP

• Project setup (TypeScript + tsup)
• URL parsing implementation
• GitHub provider implementation
• File/folder download basic functionality
• CLI basic interface
• npm package structure
• npm publish

Phase 2 - Extended Support

• GitLab provider implementation
• Bitbucket provider implementation
• Private repository support
• File filtering

Phase 3 - Stabilization

• Test coverage
• Documentation
• Performance optimization

Key Differentiators

1. Unified file + folder support (unique)
2. Automatic branch detection (missing in github-files-fetcher)
3. Short URL syntax (missing in github-files-fetcher)
4. 3 major platform support
5. TypeScript native (type-safe, great DX)
6. Modern maintenance (most existing tools are outdated)

Reference Projects

• giget - Architecture, Provider pattern
• degit - URL parsing logic
• github-files-fetcher - File download approach