# 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](https://git-scm.com))
2. **Git LFS**: Install Git LFS ([git-lfs.github.io](https://git-lfs.github.io))

### Git LFS Installation

#### Windows

1. **Download**: Download Git LFS installer from [git-lfs.github.io](https://git-lfs.github.io)
2. **Install**: Run installer
3. **Verify**: Open command prompt and run:
   ```bash
   git lfs version
   ```

#### Linux

```bash
# Ubuntu/Debian
sudo apt install git-lfs

# Verify
git lfs version
```

#### macOS

```bash
# Using Homebrew
brew install git-lfs

# Verify
git lfs version
```

### Initial Repository Setup

1. **Initialize Git**:
   ```bash
   cd /path/to/metaverseDubai
   git init
   ```

2. **Initialize Git LFS**:
   ```bash
   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**:
   ```bash
   git add .
   git commit -m "Initial commit"
   ```

5. **Set Remote** (if using remote repository):
   ```bash
   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**:
   ```bash
   git status
   ```

2. **Add Changes**:
   ```bash
   git add <files>
   # or
   git add .
   ```

3. **Commit**:
   ```bash
   git commit -m "Descriptive commit message"
   ```

4. **Push** (if using remote):
   ```bash
   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:
   ```bash
   git lfs ls-files
   ```
3. **Clone Repository**: When cloning, Git LFS files are pulled automatically:
   ```bash
   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:
  ```bash
  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](https://www.perforce.com/downloads)
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**:
   ```bash
   git checkout -b feature/hero-asset develop
   ```

2. **Work on Feature**: Make changes, commit regularly

3. **Merge to Develop**:
   ```bash
   git checkout develop
   git merge feature/hero-asset
   ```

4. **Merge to Main** (when ready):
   ```bash
   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]