https://github.com/mgks/githubtree
Visualize folder structure of any public GitHub repository.
https://github.com/mgks/githubtree
api github structured-data visualization
Last synced: about 1 month ago
JSON representation
Visualize folder structure of any public GitHub repository.
- Host: GitHub
- URL: https://github.com/mgks/githubtree
- Owner: mgks
- License: mit
- Created: 2025-02-25T04:09:09.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-04-16T19:34:12.000Z (10 months ago)
- Last Synced: 2025-05-11T09:17:51.894Z (9 months ago)
- Topics: api, github, structured-data, visualization
- Language: JavaScript
- Homepage: https://githubtree.mgks.dev
- Size: 606 KB
- Stars: 41
- Watchers: 1
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
GitHubTree allows you to explore, navigate, and generate ASCII directory trees for any GitHub repository without cloning. Available as **Web App**, **CLI Tool**, and **Node.js Library**.
## Features
* **Instant Search:** Visualize any public repository (e.g., `facebook/react`).
* **Smart Branch Detection:** Automatically detects if a branch exists (e.g., `main` vs `master`) and switches to the default branch if needed.
* **Private Repo Access:** Securely access your private repositories using a Personal Access Token (saved locally to your browser).
* **Smart Copy:** Copy the entire directory tree as text, or copy specific file paths.
* **Visual Styles:** Toggle between Classic (└──), Slashed (/src), Minimal, and ASCII (+--).
* **Deep Linking:** Share links to specific repositories and branches (e.g., `/repo/mgks/dhwani/main`).
## For Developers: The CLI
Generate directory trees directly in your terminal. Perfect for documentation and quick checks.
### Usage (No Install)
Run via `npx` to fetch a tree instantly:
```bash
npx gh-tree user/repo
```
### Installation (Global)
```bash
npm install -g gh-tree
```
### Commands & Flags
```bash
gh-tree [flags]
Flags:
--branch, -b Specify branch (default: main)
--icons Show file/folder icons in output
--token, -t Use a specific GitHub Token
--save-token Save a token globally for future use
--help Show help
```
**Example:**
```bash
gh-tree facebook/react --icons --branch main
```
## For Builders: The NPM Package
Use the core engine to fetch trees and generate ASCII structures in your own applications.
### Installation
```bash
npm install gh-tree
```
### Usage
```javascript
import { GitHubTree } from 'gh-tree';
// 1. Initialize (Token optional, but recommended for higher rate limits)
const gt = new GitHubTree(process.env.GITHUB_TOKEN);
// 2. Fetch Tree
try {
const { tree } = await gt.getTree('mgks/githubtree', 'main');
// 3. Sort & Generate ASCII
const sorted = gt.sortTree(tree, 'folder-az');
const output = gt.generateAsciiTree(sorted, { icons: true });
console.log(output);
} catch (err) {
console.error(err);
}
```
### API Reference
#### `new GitHubTree(token?)`
Creates a new instance.
* `token` (string, optional): GitHub Personal Access Token.
#### `getTree(repo, branch?)`
Fetches the raw recursive tree from GitHub API.
* Returns: `{ tree: Array, truncated: Boolean }`
#### `sortTree(tree, method?)`
Sorts the tree array.
* `method`: `'folder-az'` (default), `'folder-za'`, `'alpha-az'`, `'alpha-za'`.
#### `generateAsciiTree(tree, options?)`
Converts the tree array into a formatted string.
* `options.icons`: Boolean. If true, adds emojis (📁/📄).
## Development (Monorepo)
This repository is organized as a Monorepo.
* `packages/core`: The logic, API fetcher, and CLI tool.
* `packages/web`: The Vite-based Web Application.
* `tools/`: Scripts for generating SEO static pages.
### Local Setup
1. **Clone:**
```bash
git clone https://github.com/mgks/GitHubTree.git
cd GitHubTree
```
2. **Install:**
```bash
npm install
```
3. **Run Web App:**
```bash
npm run dev
```
4. **Build & Generate SEO Pages:**
```bash
npm run deploy
```
## License
MIT
> **{ github.com/mgks }**
>
>  
