🐙 GitHub Clone

A full-stack GitHub-inspired platform built with the MERN stack — supporting real Git operations, issues, pull requests, commit history, branch management, and real-time notifications.

Warning

⚠️ Active Development Notice There are currently some known issues on the frontend side. I'm actively working on them in my free time. Feel free to open an issue — contributions, bug reports, and suggestions are always welcome! 🙌

🌟 Overview

GitHub Clone is a self-hosted, open-source code collaboration platform. It replicates core GitHub workflows — from creating repositories and committing files to reviewing diffs, managing branches, raising issues, and merging pull requests — all powered by real Git internals via isomorphic-git and node-git-server.

🛠 Tech Stack

Frontend

Technology	Purpose
React 19	UI framework
Vite 8	Development server & build tool
TailwindCSS 4	Utility-first styling
React Router DOM 7	Client-side routing
Socket.io Client	Real-time notifications
Lucide React	Icon library
React Markdown	Render markdown files (README preview)
React Diff View	Syntax-highlighted diff rendering
React Calendar Heatmap	Contribution activity graph
Luxon	Date/time formatting
Axios	HTTP client

Backend

Technology	Purpose
Node.js + Express 5	REST API server
MongoDB + Mongoose 9	Database & ODM
isomorphic-git	Server-side Git operations (commit, diff, branches)
node-git-server	Git HTTP smart protocol (clone, push, pull over HTTP)
Socket.io	Real-time WebSocket events
JSON Web Token (JWT)	Authentication & authorization
bcryptjs	Password hashing
dotenv	Environment variable management
fs-extra	Enhanced file system operations
cors	Cross-Origin Resource Sharing

✨ Features

🔐 Authentication — Register, login, JWT-based session management
📁 Repository Management — Create repos, browse file tree, view file contents
🌿 Branch Management — Create branches, switch branches, compare refs
📝 Commit System — Server-side commits via isomorphic-git, full commit log with diff view
🔀 Pull Requests — Create PRs, view diffs between branches, check mergeability, merge
🐛 Issues — Open issues, add comments, update open/closed status
📡 Real-Time Notifications — Socket.io broadcasts when a PR is merged
👤 Profile Page — View user profile and contribution graph
📄 README Preview — Auto-renders README.md on repo home page
🌐 Git over HTTP — Real git clone, git push, git pull via the /git endpoint

📂 Project Structure

github-clone/
├── client/                   # React frontend (Vite)
│   ├── src/
│   │   ├── components/
│   │   │   ├── Navbar.jsx
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── Register.jsx
│   │   │   ├── RepoView.jsx
│   │   │   ├── FileExplorer.jsx
│   │   │   ├── CommitHistory.jsx
│   │   │   ├── DiffView.jsx
│   │   │   ├── IssueList.jsx
│   │   │   ├── IssueDetail.jsx
│   │   │   ├── PullRequestList.jsx
│   │   │   ├── PullRequestDetails.jsx
│   │   │   ├── CreatePullRequest.jsx
│   │   │   ├── CreateRepoModal.jsx
│   │   │   ├── ProfilePage.jsx
│   │   │   └── ContributionGraph.jsx
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
│
├── server/                   # Express backend
│   ├── controllers/          # Business logic
│   ├── middleware/           # Auth middleware (JWT)
│   ├── models/               # Mongoose schemas
│   │   ├── User.js
│   │   ├── Repository.js
│   │   ├── Issue.js
│   │   └── PullRequest.js
│   ├── routes/               # API route definitions
│   │   ├── authRoutes.js
│   │   ├── repoRoutes.js
│   │   ├── issueRoutes.js
│   │   └── userRoutes.js
│   ├── gitServer.js          # node-git-server config
│   └── index.js              # Entry point
│
└── repositories/             # Bare Git repos (auto-created)

✅ Prerequisites

Make sure the following are installed on your system before proceeding:

Node.js >= 18.x — Download
npm >= 9.x (comes with Node.js)
Git >= 2.x — Download
MongoDB — Either local install or a free MongoDB Atlas cluster

🔐 Environment Setup

Server — `server/.env`

Create a .env file inside the server/ directory:

# ─── Server ────────────────────────────────────────────────
PORT=5000

# ─── MongoDB ───────────────────────────────────────────────
# Option 1: Local MongoDB
MONGODB_URI=mongodb://localhost:27017/github-clone

# Option 2: MongoDB Atlas (recommended)
MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/github-clone?retryWrites=true&w=majority

# ─── JWT ───────────────────────────────────────────────────
JWT_SECRET=your_super_secret_key_change_this_in_production
JWT_EXPIRES_IN=7d

Variable	Required	Description
`PORT`	No	Port for Express server. Defaults to `5000`
`MONGODB_URI`	Yes	MongoDB connection string
`JWT_SECRET`	Yes	Secret key for signing JWT tokens. Use a long random string in production
`JWT_EXPIRES_IN`	No	Token expiry duration. Defaults to `7d`

Tip

Generate a strong JWT secret with: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Client — `client/.env`

# ─── Backend Base URL ──────────────────────────────────────
VITE_API_BASE_URL=http://localhost:5000

Note

If you change the server port, update VITE_API_BASE_URL and the Socket.io connection URL in client/src/App.jsx accordingly.

🚀 Installation & Running

1. Clone the Repository

git clone https://github.com/<your-username>/github-clone.git
cd github-clone

2. Install Dependencies

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

3. Create the Repositories Storage Directory

The git server stores bare repos here. Create it at the project root:

mkdir -p ../repositories

4. Start the Backend

cd server
node index.js

Expected output:

MongoDB Connected
Server is running on port 5000

5. Start the Frontend

Open a new terminal tab:

cd client
npm run dev

Expected output:

  VITE v8.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/

Open http://localhost:5173 in your browser.

📡 API Reference

All API endpoints are prefixed with /api/v1. Protected routes require an Authorization: Bearer <token> header.

Auth

Method	Endpoint	Auth	Description
`POST`	`/api/v1/auth/signup`	❌	Register a new user
`POST`	`/api/v1/auth/login`	❌	Login and receive a JWT token

Repositories

Method	Endpoint	Auth	Description
`POST`	`/api/v1/repos/init`	✅	Initialize a new repository
`GET`	`/api/v1/repos/user/mine`	✅	List current user's repositories
`GET`	`/api/v1/repos/:repoId`	❌	Get repository details
`GET`	`/api/v1/repos/:repoId/files`	❌	List all files in HEAD branch
`POST`	`/api/v1/repos/:repoId/commit`	✅	Write, stage, and commit changes
`GET`	`/api/v1/repos/:repoId/commits`	❌	Get full commit history
`GET`	`/api/v1/repos/:repoId/commits/:sha/diff`	❌	Get diff for a specific commit
`GET`	`/api/v1/repos/:repoId/branches`	❌	List all branches
`POST`	`/api/v1/repos/:repoId/branches`	✅	Create a new branch
`GET`	`/api/v1/repos/:repoId/compare/:base/:head`	❌	Compare two branches

Pull Requests

Method	Endpoint	Auth	Description
`GET`	`/api/v1/repos/:repoId/prs`	❌	List all pull requests
`POST`	`/api/v1/repos/:repoId/prs`	✅	Create a new pull request
`GET`	`/api/v1/repos/:repoId/prs/:prId/mergeable`	❌	Check if PR is mergeable
`POST`	`/api/v1/repos/:repoId/prs/:prId/merge`	✅	Merge a pull request

Issues

Method	Endpoint	Auth	Description
`POST`	`/api/v1/issues/:repositoryId`	✅	Open a new issue
`GET`	`/api/v1/issues/repo/:repoId`	❌	List all issues for a repo
`GET`	`/api/v1/issues/:issueId`	❌	Get issue details & comments
`POST`	`/api/v1/issues/:issueId/comments`	✅	Add a comment to an issue
`PATCH`	`/api/v1/issues/:issueId/status`	✅	Update issue status (open/closed)

Users

Method	Endpoint	Auth	Description
`GET`	`/api/v1/users/:username`	❌	Get public profile of a user

🌐 Git Operations

This project supports real Git operations over HTTP using the Git smart HTTP protocol.

Once a repository is created via the API, you can interact with it using standard Git commands:

# Clone a repository
git clone http://localhost:5000/git/<repo-name>

# Add a remote to an existing local repo
git remote add origin http://localhost:5000/git/<repo-name>

# Push changes
git push origin main

# Pull latest changes
git pull origin main

Note

<repo-name> refers to the bare repository name stored in the repositories/ directory on the server. This is initialized automatically when you create a repo via the API.

⚡ Real-Time Events (Socket.io)

The server uses Socket.io for real-time communication. The client connects to http://localhost:5000 on app load.

Event	Direction	Description
`join_repo`	Client → Server	Join a repository's room to receive its events
`pr_merged`	Server → Client	Emitted to all room members when a PR is merged

🤝 Contributing

Contributions are welcome! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feat/amazing-feature
Commit your changes: git commit -m "feat: add amazing feature"
Push to the branch: git push origin feat/amazing-feature
Open a Pull Request on GitHub

Reporting Bugs

Found a bug or a frontend issue? Please open an issue with:

A clear title and description
Steps to reproduce
Expected vs. actual behavior
Screenshots if applicable

Note

There are currently some known issues on the frontend side. I'm working on them in my free time — feel free to open an issue or submit a PR if you spot something! 🙌

📜 License

This project is open-source and available under the MIT License.

Built with ❤️ as a learning project — inspired by GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
client		client
server		server
.gitignore		.gitignore
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🐙 GitHub Clone

📋 Table of Contents

🌟 Overview

🛠 Tech Stack

Frontend

Backend

✨ Features

📂 Project Structure

✅ Prerequisites

🔐 Environment Setup

Server — `server/.env`

Client — `client/.env`

🚀 Installation & Running

1. Clone the Repository

2. Install Dependencies

3. Create the Repositories Storage Directory

4. Start the Backend

5. Start the Frontend

📡 API Reference

Auth

Repositories

Pull Requests

Issues

Users

🌐 Git Operations

⚡ Real-Time Events (Socket.io)

🤝 Contributing

Reporting Bugs

📜 License

About

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🐙 GitHub Clone

📋 Table of Contents

🌟 Overview

🛠 Tech Stack

Frontend

Backend

✨ Features

📂 Project Structure

✅ Prerequisites

🔐 Environment Setup

Server — server/.env

Client — client/.env

🚀 Installation & Running

1. Clone the Repository

2. Install Dependencies

3. Create the Repositories Storage Directory

4. Start the Backend

5. Start the Frontend

📡 API Reference

Auth

Repositories

Pull Requests

Issues

Users

🌐 Git Operations

⚡ Real-Time Events (Socket.io)

🤝 Contributing

Reporting Bugs

📜 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

Server — `server/.env`

Client — `client/.env`