https://github.com/kubrickcode/baedal
📦 Selectively download specific files or folders from Git repositories (GitHub, GitLab, Bitbucket) with automatic branch detection
https://github.com/kubrickcode/baedal
bitbucket boilerplate cli degit developer-tools devtools download downloader fetch file-fetcher giget git git-tools github gitlab npm repository scaffolding template
Last synced: 7 days ago
JSON representation
📦 Selectively download specific files or folders from Git repositories (GitHub, GitLab, Bitbucket) with automatic branch detection
- Host: GitHub
- URL: https://github.com/kubrickcode/baedal
- Owner: KubrickCode
- License: mit
- Created: 2025-10-10T10:10:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T18:26:32.000Z (15 days ago)
- Last Synced: 2026-01-12T23:59:03.381Z (15 days ago)
- Topics: bitbucket, boilerplate, cli, degit, developer-tools, devtools, download, downloader, fetch, file-fetcher, giget, git, git-tools, github, gitlab, npm, repository, scaffolding, template
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/baedal
- Size: 1.48 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Baedal
Simple GitHub repository downloader CLI tool.
## Requirements
- Node.js >= 18.0.0
## Installation
```bash
npm install -g baedal
# or
pnpm add -g baedal
```
## Usage
```bash
# Download entire repository
baedal pull user/repo
# Download to specific directory
baedal pull user/repo ./output
# Download specific folder or file
baedal pull user/repo/src/components ./components
# Exclude specific files or patterns
baedal pull user/repo --exclude "*.test.ts"
baedal pull user/repo --exclude "*.md" ".gitignore"
baedal pull user/repo ./output --exclude "test/**" "docs/**"
# File conflict handling
baedal pull user/repo --force # Force overwrite without confirmation
baedal pull user/repo --modified-only # Update only modified files (ignore new files)
baedal pull user/repo --no-clobber # Abort if any file would be overwritten
baedal pull user/repo --skip-existing # Skip existing files, only add new files
# Explicit GitHub prefix
baedal pull github:user/repo
# Using GitHub URL
baedal pull https://github.com/user/repo
# Note: 'pull' is the default command, so 'baedal user/repo' also works
baedal user/repo
```
## Private Repository Authentication
Baedal supports downloading from private repositories using GitHub authentication tokens.
### Using CLI Flag
```bash
baedal pull user/private-repo --token YOUR_GITHUB_TOKEN
```
### Using Environment Variables
```bash
# GitHub token
export GITHUB_TOKEN=your_github_token
# or generic token
export BAEDAL_TOKEN=your_token
# Then use baedal normally
baedal pull user/private-repo
```
### Token Generation
Create a GitHub Personal Access Token at Settings > Developer settings > Personal access tokens
- Required scope: `repo` (for private repositories)
## Features
- Download from GitHub repositories
- Support for private repositories with authentication tokens
- Support for specific folders/files
- Exclude specific files or patterns using glob patterns
- File conflict handling modes (force, modified-only, no-clobber, skip-existing)
- Automatic branch detection (main/master)
- Multiple input formats (prefix, URL, or simple user/repo)
- Zero configuration
- Robust error handling with structured error classes (BaseError hierarchy)
- Standardized logging with testable logger utility
- Provider-based architecture for future multi-provider support
- Enhanced CLI input validation for early error detection
## Library Usage
```typescript
import { baedal } from "baedal";
// Basic usage
await baedal("user/repo");
await baedal("user/repo", "./output");
await baedal("user/repo/src", "./src");
// With exclude option
await baedal("user/repo", "./output", {
exclude: ["*.test.ts", "*.md", "test/**"],
});
// Exclude without specifying destination (uses current directory)
await baedal("user/repo", {
exclude: ["*.test.ts", "docs/**"],
});
// File conflict handling (using ConflictMode)
await baedal("user/repo", "./output", {
conflictMode: { mode: "force" }, // Force overwrite without confirmation
});
await baedal("user/repo", "./output", {
conflictMode: { mode: "modified-only" }, // Update only modified files (ignore new files)
});
await baedal("user/repo", "./output", {
conflictMode: { mode: "no-clobber" }, // Abort if any file would be overwritten
});
await baedal("user/repo", "./output", {
conflictMode: { mode: "skip-existing" }, // Skip existing files, only add new files
});
// Legacy conflict handling (still supported)
await baedal("user/repo", "./output", {
force: true, // Deprecated: use conflictMode instead
});
// Private repository with token
await baedal("user/private-repo", "./output", {
token: process.env.GITHUB_TOKEN,
});
// Using GitHub URL
await baedal("https://github.com/user/repo");
await baedal("https://github.com/user/repo/src", "./src");
```
## Contributing
This project started as a small personal project with a development environment highly tailored to the owner. Given the low probability of external contributors, the current setup is unlikely to change.
If you'd like to contribute, please contact kubrickcode@gmail.com and we'll adapt the environment to accommodate contributions.
### Development Guidelines
- **Commit Format**: Follow [Conventional Commits](https://www.conventionalcommits.org/) specification
- **Additional Info**: See [CLAUDE.md](./CLAUDE.md) for detailed development guidelines
### Running Tests
```bash
# Run all tests
pnpm test
# Run tests with coverage
pnpm test -- --coverage
# Run tests in watch mode
pnpm test -- --watch
```
## License
MIT