GitForge

A Git-Inspired Version Control System Built from Scratch

Features • Tech Stack • Installation • Usage • API Documentation

📖 Overview

GitForge is an educational project that recreates Git's core functionality from the ground up to understand how version control systems work internally. It implements fundamental Git commands like init, add, commit, push, pull, and revert, while leveraging AWS S3 for remote storage instead of traditional Git servers.

This project combines a CLI tool for local version control operations with a full-stack web application for repository management, user authentication, and collaboration features.

🎯 Project Goals

Learn Git Internals: Understand how Git tracks changes, creates commits, and manages file snapshots
Cloud Storage Integration: Use AWS S3 as a remote repository storage solution
Full-Stack Development: Build a complete ecosystem with CLI tools and web interface
Real-World Application: Implement authentication, authorization, and collaboration features

✨ Features

🛠️ CLI Version Control

init - Initialize a new GitForge repository (.gitForge directory)
add <file> - Stage files for commit (move to staging area)
commit <message> - Create a snapshot with unique commit ID (UUID)
push - Upload commits to AWS S3 bucket
pull - Download commits from AWS S3 bucket
revert <commitID> - Revert repository to a specific commit

🌐 Web Application

User Management
- User registration and authentication (JWT-based)
- User profiles with activity heatmaps
- Password encryption with bcrypt
Repository Management
- Create and manage repositories
- Public/private visibility settings
- Star repositories
- Repository content browsing
Issue Tracking
- Create and manage issues
- Link issues to repositories
- Issue collaboration
Real-time Features
- WebSocket integration with Socket.IO
- Live updates and notifications

🛠️ Tech Stack

Backend

Technology	Purpose
	JavaScript runtime environment
	Web application framework
	NoSQL database for user/repo data
	MongoDB object modeling
	Cloud storage for commits
	Real-time bidirectional communication
	Authentication & authorization
	CLI command parsing
	Unique commit ID generation

Frontend

Technology	Purpose
	UI library
	Build tool & dev server
	Client-side routing
	Utility-first CSS framework
	HTTP client
	GitHub's design system

📂 Project Structure

GitForge/
├── backend/
│   ├── config/
│   │   └── aws-config.js          # AWS S3 configuration
│   ├── controllers/
│   │   ├── init.js                # Initialize repository
│   │   ├── add.js                 # Stage files
│   │   ├── commit.js              # Create commits
│   │   ├── push.js                # Upload to S3
│   │   ├── pull.js                # Download from S3
│   │   ├── revert.js              # Revert to commit
│   │   ├── userController.js      # User operations
│   │   ├── repoController.js      # Repository operations
│   │   └── issueController.js     # Issue operations
│   ├── middleware/
│   │   ├── authMiddleware.js      # JWT authentication
│   │   └── authorizeMiddleware.js # Authorization checks
│   ├── models/
│   │   ├── userModel.js           # User schema
│   │   ├── repoModel.js           # Repository schema
│   │   └── issueModel.js          # Issue schema
│   ├── routes/
│   │   ├── user.router.js         # User endpoints
│   │   ├── repo.router.js         # Repository endpoints
│   │   └── issue.router.js        # Issue endpoints
│   ├── index.js                   # Entry point & CLI
│   └── package.json
│
└── frontend/
    ├── src/
    │   ├── components/
    │   │   ├── auth/              # Login & Signup
    │   │   ├── dashboard/         # Main dashboard
    │   │   ├── repo/              # Repository components
    │   │   ├── user/              # User profile & heatmap
    │   │   └── issue/             # Issue components
    │   ├── authContext.jsx        # Auth state management
    │   ├── ProjectRoutes.jsx      # Route configuration
    │   └── App.jsx
    └── package.json

🚀 Installation

Prerequisites

Node.js (v16 or higher)
MongoDB (local or Atlas)
AWS Account with S3 bucket access
Git (for cloning the repository)

1️⃣ Clone the Repository

git clone https://github.com/prathampmp23/GitForge-Backend
cd GitForge

2️⃣ Backend Setup

cd backend
npm install

Create a .env file in the backend directory:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/gitforge
JWT_SECRET=your_jwt_secret_key_here

# AWS Configuration
AWS_REGION=your-aws-region
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
S3_BUCKET=your-s3-bucket-name

3️⃣ Frontend Setup

cd ../frontend
npm install

Create a .env file in the frontend directory (if needed):

VITE_API_URL=http://localhost:3000

4️⃣ AWS S3 Setup

Create an S3 bucket in your AWS account
Configure IAM user with S3 access permissions
Update the .env file with your credentials

💻 Usage

Running the Web Application

Start Backend Server:

cd backend
npm start

Server will run on http://localhost:3000

Start Frontend Dev Server:

cd frontend
npm run dev

Frontend will run on http://localhost:5173

Using the CLI Tool

Navigate to any directory where you want to use GitForge:

Initialize a Repository:

node backend/index.js init

Add Files to Staging:

node backend/index.js add myfile.txt

Commit Changes:

node backend/index.js commit "Initial commit"

Push to S3:

node backend/index.js push

Pull from S3:

node backend/index.js pull

Revert to a Commit:

node backend/index.js revert <commit-id>

🔍 How It Works

Internal Architecture

1. Repository Initialization

When you run init, GitForge creates a .gitForge directory with:

.gitForge/
├── config.json       # Configuration (S3 bucket name)
├── commits/          # Stores all commits locally
└── staging/          # Temporary area for files to be committed

2. Adding Files

The add command copies files from your working directory to the .gitForge/staging area.

3. Creating Commits

The commit command:

Generates a unique UUID for the commit
Creates a new directory under .gitForge/commits/<uuid>/
Copies all files from staging to the commit directory
Saves metadata in commit.json (message, timestamp)

4. Push to Cloud

The push command:

Reads all commit directories
Uploads each file to S3 with the structure: commits/<commit-id>/<filename>
Uses AWS SDK for file transfer

5. Pull from Cloud

Downloads commits from S3 back to local .gitForge/commits directory.

6. Revert Operation

Restores your working directory to the state of a specific commit.

📡 API Documentation

Authentication Endpoints

POST /auth/register    - Register new user
POST /auth/login       - Login user (returns JWT token)
GET  /auth/profile     - Get current user profile

Repository Endpoints

POST   /repos          - Create new repository
GET    /repos          - Get all repositories
GET    /repos/:id      - Get repository by ID
PUT    /repos/:id      - Update repository
DELETE /repos/:id      - Delete repository
POST   /repos/:id/star - Star/unstar a repository

Issue Endpoints

POST   /repos/:repoId/issues     - Create issue
GET    /repos/:repoId/issues     - Get all issues
GET    /issues/:id                - Get issue by ID
PUT    /issues/:id                - Update issue
DELETE /issues/:id                - Delete issue

🎓 Learning Outcomes

By building GitForge, you'll understand:

✅ Version Control Internals: How Git tracks file changes using snapshots
✅ File System Operations: Reading, writing, and managing directories in Node.js
✅ Cloud Storage: Integrating AWS S3 for persistent storage
✅ CLI Development: Building command-line tools with Yargs
✅ Full-Stack Architecture: Connecting frontend, backend, and cloud services
✅ Authentication: Implementing JWT-based auth with bcrypt
✅ Real-time Communication: Using WebSockets with Socket.IO
✅ Database Design: Modeling relationships with MongoDB and Mongoose

🤝 Contributing

Contributions are welcome! Feel free to:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is open source and available under the ISC License.

🙏 Acknowledgments

Inspired by the internal workings of Git
Built as an educational project to understand version control systems
Thanks to the open-source community for the amazing tools and libraries

📧 Contact

Project Maintainer: Pratham Potdar

GitHub: @prathampmp23

Made with ❤️ to understand Git better

⭐ Star this repo if you found it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
config		config
controllers		controllers
middleware		middleware
models		models
routes		routes
.gitignore		.gitignore
README.md		README.md
commit.json		commit.json
hello.txt		hello.txt
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

prathampmp23/GitForge-Backend

Folders and files

Latest commit

History

Repository files navigation