metaverseDubai/VERSION_CONTROL.md

Version Control Setup - Dubai Metaverse

Overview

This document covers version control setup for the Dubai Metaverse project. Due to the large file sizes (textures, models, .uasset files), Git LFS (Large File Storage) is required, or Perforce can be used as an alternative.

Option 1: Git with Git LFS (Recommended for Small Teams)

Prerequisites

1. Git: Install Git (git-scm.com)
2. Git LFS: Install Git LFS (git-lfs.github.io)

Git LFS Installation

Windows

1. Download: Download Git LFS installer from git-lfs.github.io
2. Install: Run installer
3. Verify: Open command prompt and run:

   git lfs version
   

Linux

# Ubuntu/Debian
sudo apt install git-lfs

# Verify
git lfs version

macOS

# Using Homebrew
brew install git-lfs

# Verify
git lfs version

Initial Repository Setup

1. Initialize Git:

   cd /path/to/metaverseDubai
   git init
   

2. Initialize Git LFS:

   git lfs install
   

3. Configure Git LFS Tracking:

   The .gitattributes file (already created) configures Git LFS tracking. Key file types tracked:

   • .uasset - Unreal asset files
   • .umap - Unreal map files
   • .png, .jpg, .tga - Texture files
   • .fbx, .obj - 3D model files
   • .wav, .mp3 - Audio files

4. Add Files:

   git add .
   git commit -m "Initial commit"
   

5. Set Remote (if using remote repository):

   git remote add origin <repository-url>
   git push -u origin main
   

Git LFS Configuration

The .gitattributes file defines which files are tracked by Git LFS:

# Unreal Engine files
*.uasset filter=lfs diff=lfs merge=lfs -text
*.umap filter=lfs diff=lfs merge=lfs -text

# Textures
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text

# 3D Models
*.fbx filter=lfs diff=lfs merge=lfs -text
*.obj filter=lfs diff=lfs merge=lfs -text

# Audio
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text

Git Workflow

Branching Strategy

• main: Production-ready code
• develop: Development branch
• feature/: Feature branches (e.g., feature/hero-asset)
• hotfix/: Hotfix branches for urgent fixes

Committing Changes

1. Check Status:

   git status
   

2. Add Changes:

   git add <files>
   # or
   git add .
   

3. Commit:

   git commit -m "Descriptive commit message"
   

4. Push (if using remote):

   git push origin <branch>
   

Commit Message Guidelines

• Format: Type: Brief description
• Types: feat, fix, docs, style, refactor, test, chore
• Example: feat: Add Cayan Tower hero asset

Git LFS Best Practices

1. Large Files: Always use Git LFS for large files
2. Check Tracking: Verify files are tracked:

   git lfs ls-files
   

3. Clone Repository: When cloning, Git LFS files are pulled automatically:

   git clone <repository-url>
   git lfs pull
   

Repository Size Management

• Expected Size: 50-100GB+ with Git LFS
• Storage: Ensure adequate storage space
• Cleanup: Periodically clean up unused files:

  git lfs prune
  

---

Option 2: Perforce Helix Core (Recommended for Large Teams)

Prerequisites

1. Perforce Server: Set up Perforce server or use cloud service
2. Perforce Client: Install P4V (Perforce Visual Client)

Perforce Setup

1. Install P4V: Download from perforce.com
2. Connect to Server: Configure connection to Perforce server
3. Create Workspace: Set up workspace for project
4. Configure Streams: Set up stream structure:
   • Main: Production stream
   • Development: Development stream
   • Feature Streams: Feature-specific streams

Perforce Workflow

1. Check Out Files: Check out files before editing
2. Make Changes: Edit files in Unreal Editor
3. Submit Changes: Submit changes to server
4. Sync: Sync latest changes from server

Perforce Integration with Unreal

Unreal Engine has built-in Perforce integration:

1. Edit > Source Control > Connect to Source Control
2. Select Perforce
3. Configure Settings:
   • Server address
   • Username
   • Workspace
4. Connect: Connect to Perforce server

---

Unreal Engine Source Control Integration

Setting Up Source Control in Unreal

1. Edit > Source Control > Connect to Source Control
2. Select Provider: Choose Git or Perforce
3. Configure Settings:
   • Git: Repository path, user name, email
   • Perforce: Server, username, workspace
4. Connect: Connect to source control

Using Source Control in Unreal

• Check Out: Right-click asset > Source Control > Check Out
• Submit: Right-click asset > Source Control > Submit
• Revert: Right-click asset > Source Control > Revert
• Sync: Source Control > Sync Latest

Source Control Icons

• Green Check: File is checked out
• Red X: File needs update
• Blue Plus: New file to add
• Yellow Arrow: File has conflicts

---

File Organization for Version Control

Files to Track

• ✅ .uproject - Project file
• ✅ .uasset - Asset files (via Git LFS)
• ✅ .umap - Map files (via Git LFS)
• ✅ Source code (if using C++)
• ✅ Configuration files (.ini)
• ✅ Documentation (.md)
• ✅ Scripts (.sh, .py)

Files to Ignore

• ❌ Binaries/ - Compiled binaries
• ❌ Intermediate/ - Intermediate build files
• ❌ Saved/ - Saved editor data
• ❌ DerivedDataCache/ - Derived data cache
• ❌ *.sln - Visual Studio solution files (optional)
• ❌ *.suo - Visual Studio user options

See .gitignore for complete ignore list.

---

Branching Strategy

Main Branches

• main: Production-ready, stable code
• develop: Integration branch for features

Supporting Branches

• feature/: New features (e.g., feature/hero-asset)
• hotfix/: Urgent fixes (e.g., hotfix/performance-issue)
• release/: Release preparation (e.g., release/v1.0)

Workflow

1. Create Feature Branch:

   git checkout -b feature/hero-asset develop
   

2. Work on Feature: Make changes, commit regularly

3. Merge to Develop:

   git checkout develop
   git merge feature/hero-asset
   

4. Merge to Main (when ready):

   git checkout main
   git merge develop
   

---

Collaboration Best Practices

Before Committing

1. ✅ Validate assets (naming, quality)
2. ✅ Test in editor
3. ✅ Check for conflicts
4. ✅ Write descriptive commit messages

Communication

• Large Changes: Notify team before large commits
• Breaking Changes: Document breaking changes
• Asset Updates: Communicate asset updates
• Merge Conflicts: Resolve conflicts promptly

Regular Syncing

• Pull/Sync: Regularly pull latest changes
• Push/Submit: Push changes regularly (don't let work accumulate)
• Conflicts: Resolve conflicts immediately

---

Troubleshooting

Git LFS Issues

Files Not Tracked:

• Solution: Verify .gitattributes is correct
• Solution: Re-track files: git lfs track "*.uasset"

Large Repository:

• Solution: Use Git LFS for all large files
• Solution: Clean up unused files: git lfs prune

Clone Issues:

• Solution: Ensure Git LFS is installed
• Solution: Run git lfs pull after clone

Perforce Issues

Connection Issues:

• Solution: Verify server address and credentials
• Solution: Check network connectivity
• Solution: Verify workspace configuration

Checkout Issues:

• Solution: Verify file is not checked out by another user
• Solution: Check workspace permissions

---

Security Considerations

API Keys and Secrets

• Never Commit: API keys, passwords, secrets
• Use Environment Variables: Store secrets in environment variables
• Use .gitignore: Add secret files to .gitignore

Asset Security

• Proprietary Assets: Protect proprietary assets
• Access Control: Use repository access controls
• Backup: Regular backups of repository

---

Version: 1.0 Last Updated: [Current Date]