Download exactly what you need from GitHub.
SubRepo is a clean, developer-first tool for downloading subdirectories from GitHub repositories as ZIP files. No more cloning entire repositories just to get a single folder.
- Download Any Subdirectory - Grab specific folders from any public GitHub repository
- Full Content Downloads - Uses GitHub's ZIPBALL API to ensure complete file content (not shallow metadata)
- Accurate Size Estimation - Recursive Git Tree API provides 96%+ accurate size calculations before download
- Private Repository Support - Use your GitHub access token to download from private repos
- Real-time Progress - Watch your download progress with live updates via Server-Sent Events (SSE)
- Parallel Downloads - Files are downloaded concurrently for maximum speed
- Direct Streaming - Repository archives are streamed directly without server-side storage
- Branch Support - Works with any branch, not just
mainormaster - No Installation Required - Works entirely in your browser
- Paste a GitHub URL pointing to a folder (e.g.,
https://github.com/owner/repo/tree/main/src/components) - Click "Check link" to validate the URL and see accurate folder details (size, file count)
- Click "Download folder" to get your ZIP file
- The download streams directly to your browser with real-time progress
+-------------------------------------------------------------+
| Frontend |
| React + Vite + Zustand (State Management) |
| Port: 5000 |
+--------------------------+----------------------------------+
| HTTP (REST API + SSE)
v
+-------------------------------------------------------------+
| Backend |
| Spring Boot (Java 17) |
| Port: 8080 |
| +-------------+ +-------------+ +-------------+ |
| | Controller |--+ Service +--+ Utility | |
| +-------------+ +-------------+ +-------------+ |
+--------------------------+----------------------------------+
| GitHub REST API
v
+-------------------------------------------------------------+
| GitHub API |
| - ZIPBALL API (download full repository archives) |
| - Git Tree API (recursive file/size calculation) |
| - Contents API (directory browsing) |
| - Repository API (get default branch) |
+-------------------------------------------------------------+
- Java 17 with Spring Boot 3.2.0
- WebClient for async GitHub API calls
- GitHub ZIPBALL API for complete repository downloads
- Git Tree API for accurate recursive size calculation
- Parallel Stream Processing for concurrent file downloads
- Server-Sent Events (SSE) for real-time progress streaming
- In-memory ZIP creation - no disk storage required
- React 18 with Vite
- Zustand for state management
- Modern, minimal UI with warm beige palette (#F5F1E8, #EEE8DC)
- Bottle green accents (#004D38)
POST /api/validate
Content-Type: application/json
{
"url": "https://github.com/owner/repo/tree/main/folder",
"token": "ghp_xxx" // optional
}
Response:
{
"valid": true,
"owner": "owner",
"repo": "repo",
"branch": "main",
"path": "folder",
"fileCount": 15,
"folderCount": 3,
"estimatedSize": 125000
}GET /api/download?url={encoded_url}&token={optional_token}
Accept: text/event-stream
Event Types:
progress- Download progress updates with file counts, bytes downloaded, current filecomplete- Download finished, includes base64 ZIP dataerror- Error occurred during download
- Java 17+
- Node.js 18+
- Maven 3.8+
cd backend
mvn spring-boot:runThe backend runs on port 8080.
cd frontend
npm install
npm run devThe frontend runs on port 5000 with a proxy to the backend.
| Variable | Description | Default |
|---|---|---|
GITHUB_TOKEN |
Default GitHub token for API requests | None |
SERVER_PORT |
Backend server port | 8080 |
subrepo/
+-- backend/
| +-- src/main/java/com/gitdownloader/
| | +-- config/ # CORS and WebClient configuration
| | +-- controller/ # REST API controllers
| | +-- dto/ # Data transfer objects
| | +-- exception/ # Global exception handling
| | +-- service/ # Business logic (GitHub API, ZIP creation)
| | +-- util/ # URL parsing utilities
| +-- BACKEND_DOCUMENTATION.md # Detailed backend documentation
| +-- pom.xml
+-- frontend/
| +-- src/
| | +-- components/ # React components (URLInput, TokenInput, etc.)
| | +-- pages/ # Page components (HomePage)
| | +-- services/ # API service layer
| | +-- store/ # Zustand state management
| | +-- styles/ # CSS styles
| +-- vite.config.js
| +-- package.json
+-- README.md
+-- replit.md
GitHub API has rate limits that affect SubRepo:
| Authentication | Requests per Hour |
|---|---|
| No token | 60 |
| With token | 5,000 |
For large folders (100+ files), a token is strongly recommended.
The application gracefully handles:
- Invalid GitHub URLs with clear error messages
- Non-existent repositories or paths
- Rate limit errors with user-friendly messages
- Private repository access attempts (prompts for token)
- Network failures and timeouts
- Large Repositories: Very large repositories (>500MB) may take longer to download
- Memory Usage: The ZIPBALL approach loads the entire repository into memory temporarily
- GitHub API Limits: Rate limits still apply (5,000/hour with token, 60/hour without)
- Subfolder Filtering: When downloading a subfolder, the entire repo is fetched then filtered (GitHub API limitation)
SubRepo features a calm, developer-first aesthetic:
- Warm beige palette - Easy on the eyes for extended use
- Bottle green accents - Professional, understated highlights
- Space Grotesk font - Modern, geometric heading typography
- Left-aligned layout - Clean, readable interface
- Step-wise progress - Visual feedback during downloads with ETA
For detailed backend documentation including line-by-line explanations of all Java files, see:
Created by Himanchal Kaushale
Inspired by download-directory.github.io
MIT License - feel free to use this project for personal or commercial purposes.