GitFolderDownloader

rocket_launchQuick Start

linkSmart Links

You can generate direct download links for your team or documentation using the URL query feature.

How it works:

Append the GitHub URL after ?= to the Git Folder Downloader URL:

When a user opens this link, Git Folder Downloader will automatically launch, fetch the files, and prepare the download without any user input.

Advanced URL Parameters

• &st=0 → Start file index (zero-based) for partial folder downloads
• &mx=10 → Max file index (non-inclusive end index) for partial folder downloads
• &name=my-backup.zip → Custom filename (no extension required; .zip will be added if missing)
• &return=https://mysite.com/thank-you → Redirect after download (API/headless mode)

Examples

terminalHeadless API Mode (detailed)

The /api/ endpoint (headless mode) is designed for automated downloads and link integrations. It runs without UI inputs and supports the same options as the main app through query parameters.

Behavior

• Resolves repository metadata (default branch) if the link points to a repo root.
• Fetches the Git tree recursively for folders and builds a ZIP preserving folder structure.
• Handles single-file downloads (supports forced ZIP via global setting in non-API mode; API endpoint will save single files directly unless .zip requested via &name).
• Performs chunked downloads with concurrency (up to 5 simultaneous fetches) to improve performance while being considerate to rate limits.
• After completion the endpoint will attempt to return:
  1. Redirect to &return if provided and valid,
  2. otherwise go back in history if available,
  3. otherwise close the tab (or show a "close tab" message when not permitted).

Request Parameters Recap

Progress & Feedback

The API page provides a simple progress card: title, numeric progress text, and a progress bar. When using the API from other pages, the calling page should handle UX (e.g., show a spinner while the new tab runs the API).

Errors & Exit Codes

• Missing URL — page will show "Missing URL."
• Invalid GitHub URL — non-GitHub or malformed URL.
• Folder empty / No files found — thrown when selected path contains no blobs.
• Network Error — returned when raw content fetch fails (uncommon but possible).
• API errors — GitHub API errors (e.g., rate limit, repo not found) return GitHub's message.

Security & Tokens

For private repositories you must provide a Personal Access Token (PAT). The app stores it locally in localStorage. Recommended minimal scope:

• repo — gives full control of private repositories (required for reading private content via the API). For public-only usage, no token is required.

Important: Keep tokens secure — only use PATs you control. The app never sends tokens anywhere except to GitHub's API from your browser session.

Performance Notes

• Files are downloaded in batches of up to 5 concurrent requests for speed and to reduce hitting API rate limits quickly.
• If you plan to download very large repositories frequently, consider using a token and respecting GitHub rate limits.

settingsSettings

Click the Gear icon to open settings:

• GitHub Token: Paste your Personal Access Token for private repo downloads. Stored locally only.
• Force ZIP: Force single files to download as ZIP (global behavior in web UI — note headless API will respect filename).
• Theme & Accent: Choose from 8+ themes or a custom accent color. Accent colors and theme selection are stored locally.

view_weekPartial Folder Download (start/mx)

Use &st and &mx to target a specific range of files inside a folder. This is useful for:

• Large folders where downloading the whole tree is slow or unnecessary.
• Splitting a folder into multiple archives (e.g., ?st=0&mx=100, ?st=100&mx=200).

Indexing rules:

• Indexes are zero-based (first file is st=0).
• mx is treated as the end index (non-inclusive) — the code uses slice(start, end).
• If st >= mx or values are invalid, the script falls back to downloading the entire selection.

pending_actionsPreview & Progress

Before downloading, Git Folder Downloader shows a live preview of the first 50 files and a progress bar during the download process. The API/headless page also exposes a simple progress UI (title, numeric status, and a bar).

extensionBrowser Extension / GitHub Integration

The integration script injects a small "Download" menu item into GitHub's context/action lists and provides a lightweight modal to configure name, st, and mx.

What the extension does

• Detects the current GitHub page context (repo root, folder, or file) using the URL path.
• Inserts a "Download Repo", "Download Folder", or "Download" menu item into GitHub's action lists.
• Shows a modal where you can set: Name, st (start) and mx (max).
• Builds a final /api/ URL with parameters and opens it in a new tab to run the headless download.
• Uses a MutationObserver so it keeps working as GitHub updates the DOM.

Modal Options

• Name — the file name for the generated ZIP (if folder) or file. If you omit the extension, .zip will be added for folder downloads.
• st — start index (numeric). Leave empty to begin at index 0.
• mx — max index (numeric). Leave empty to use the folder's total file count.

How it constructs the URL

Installation / Usage

1. Install the browser extension or add this script as a userscript (Tampermonkey/Violentmonkey) — the injector relies on the modern GitHub DOM structure.
2. Open any GitHub repo/folder/file and open the action list (three-dot menu / context menu). You will see a new "Download ..." item inserted.
3. Click the item, set the options in the modal, and click Download. The API page opens in a new tab and performs the download.

Compatibility & Notes

• Works with GitHub's current interface and uses MutationObserver to re-insert the item if GitHub re-renders menus.
• Because the injector is DOM-based, any major GitHub layout change may break detection — you can update the script to match new CSS structures.
• The injected menu item uses accessible markup but is implemented as a convenience — it does not require special GitHub permissions.

helpTroubleshooting & FAQ

Why do I get "No files in selected range"?

Check your st and mx values — they are zero-based indices. If st ≥ mx, the script will fallback to downloading everything.

Network errors / raw.githubusercontent blocked

Raw content is fetched from raw.githubusercontent.com. If you see network errors, check your network, ad-blockers, or corporate proxies. Private repos require a token — raw fetch won't work for private content.

Token scopes — what do I need?

For private content, provide a PAT with repo scope. For read-only public access, you do not need a token.

Rate limits & failures

GitHub imposes rate limits on unauthenticated and authenticated requests. If you download many large repos quickly, you may hit rate limits. Using a token increases your rate limit quota.

Download takes too long

Large repos can be slow. Use &st and &mx to download in chunks. JSZip keeps everything client-side so memory is a limiting factor for very large zips.

auto_awesomeFeatures