LegacyERP Core System – Version Control Repository Creation Guide

Project Overview

Objective: Establish a standardized, secure, and collaborative Git repository for the “LegacyERP Core System,” supporting both new project initialization and migration of an existing codebase, with branch strategy, access control, and end-to-end verification.

Prerequisites

Ensure the following tools and access are ready:

• Workstation with:
  • Git 2.34+ installed
  • Terminal or shell access
  • OpenSSH client
• Account on at least one code hosting platform with repository creation rights:
  • GitHub, GitLab, or Bitbucket
• Two-factor authentication enabled on the chosen platform (recommended)
• Network access to the hosting platform and SSH over port 22

Verify Git and set global configuration:

git --version
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
# Line endings (choose one)
# Windows:
git config --global core.autocrlf true
# macOS/Linux:
git config --global core.autocrlf input

Generate and add an SSH key (recommended for authentication):

# Create an Ed25519 key
ssh-keygen -t ed25519 -C "your.email@example.com"
# Start agent and add key (Git Bash/macOS/Linux)
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Copy public key to clipboard, then add it in the platform’s SSH keys settings
# macOS:
pbcopy < ~/.ssh/id_ed25519.pub
# Linux:
xclip -sel clip < ~/.ssh/id_ed25519.pub  # or cat ~/.ssh/id_ed25519.pub
# Windows (PowerShell):
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

Test SSH connectivity (run the one matching your platform):

ssh -T git@github.com
ssh -T git@gitlab.com
ssh -T git@bitbucket.org

Optional credential helpers (HTTPS use only):

# Windows:
git config --global credential.helper manager-core
# macOS:
git config --global credential.helper osxkeychain
# Linux (if libsecret installed):
git config --global credential.helper libsecret

Detailed Steps

1) Environment Preparation

• Confirm Git config is set as above.
• Confirm SSH key is registered and connectivity test succeeds.
• Confirm you have create-repository permissions in the target organization/group.

2) Repository Initialization (Local)

Choose one of the following initialization paths.

A. New repository (no existing Git history):

mkdir legacyerp-core && cd legacyerp-core
git init -b main
printf "# LegacyERP Core System\n\nRepository for the core system codebase.\n" > README.md

# Minimal, language-agnostic .gitignore
cat > .gitignore << 'EOF'
# OS
.DS_Store
Thumbs.db

# Editors/IDE
.vscode/
.idea/
*.swp

# Build/Artifacts
build/
dist/
target/
bin/
obj/
*.log

# Dependency caches (common)
.node_modules/
.venv/
vendor/
packages/
EOF

git add .
git commit -m "Initialize LegacyERP Core System repository"

B. Migration from an existing Git codebase (preserve history):

# In existing project working directory
# Ensure the default branch is 'main'
git branch -m master main 2>/dev/null || true
git branch -m MAIN main 2>/dev/null || true

# Clean up any stale references
git remote remove origin 2>/dev/null || true

# Add minimal .gitignore if not present
[ -f .gitignore ] || cat > .gitignore << 'EOF'
.DS_Store
Thumbs.db
.vscode/
.idea/
*.swp
build/
dist/
target/
bin/
obj/
*.log
EOF

git add .gitignore
git commit -m "Add baseline .gitignore" || true

Optional: Configure Git LFS for large binary assets (before adding large files):

# Install Git LFS (follow your OS instructions), then:
git lfs install
# Example patterns; customize as needed for binaries >10MB
git lfs track "*.psd" "*.zip" "*.bin" "*.iso"
git add .gitattributes
git commit -m "Configure Git LFS for large binaries" || true

3) Remote Repository Creation and Association

Create an empty repository named “LegacyERP-Core-System” on your chosen platform.

• GitHub (web): Organization > New repository > Name: LegacyERP-Core-System > Private (recommended) > Create
• GitHub (CLI, optional):

gh repo create ORG/LegacyERP-Core-System --private --description "LegacyERP Core System"

• GitLab (web): Group > New project/repository > Project name: LegacyERP-Core-System > Visibility: Private > Create
• GitLab (CLI, optional):

glab repo create ORG/LegacyERP-Core-System --private --name "LegacyERP Core System"

• Bitbucket (web): Workspace > Create repository > Name: LegacyERP-Core-System > Access level: Private > Create

Associate the local repository with the remote and push:

# Replace placeholders accordingly:
# GitHub:
git remote add origin git@github.com:ORG/LegacyERP-Core-System.git
# GitLab:
# git remote add origin git@gitlab.com:GROUP/LegacyERP-Core-System.git
# Bitbucket:
# git remote add origin git@bitbucket.org:WORKSPACE/LegacyERP-Core-System.git

git push -u origin main

Create and push the develop branch:

git checkout -b develop
git push -u origin develop
git checkout main

4) Branch Strategy Configuration

Adopt the following branch model:

• main: production-ready code, protected
• develop: integration branch
• feature/*: short-lived branches for new work
• release/*: stabilization before release
• hotfix/*: urgent fixes branched from main

Create initial branch patterns (locally, as needed):

# Example feature branch template usage:
git checkout -b feature/initial-setup develop
# After work, push:
git push -u origin feature/initial-setup

Configure branch protection in the platform:

• GitHub:

  • Settings > Branches > Add rule > Branch name pattern: main
    • Require a pull request before merging
    • Require approvals: 1
    • Block force pushes
    • Block deletions
    • Optional: Require linear history; Require signed commits
  • Add a rule for develop with similar restrictions (adjust approvals as needed).

• GitLab:

  • Settings > Repository > Protected Branches
  • Protect main: No one can push directly (Maintainers can merge via MR)
  • Protect develop similarly; adjust push/merge permissions per policy.

• Bitbucket:

  • Repository settings > Branch permissions
  • Add permission for main:
    • Restrict push to admins
    • Require pull request
  • Add permission for develop with appropriate restrictions.

Optional policies:

• Enforce pull requests for all changes to main and develop.
• Restrict who can merge (e.g., Maintainers only).
• Optional status checks can be enabled when CI is available.

5) Collaboration and Access Control

Assign repository permissions:

• GitHub:

  • Organization > Teams > Create team “LegacyERP Core”
  • Add members; set role (e.g., Maintain/Write as needed)
  • Grant the team access to the repository
  • Optional: CODEOWNERS to define required reviewers

    mkdir -p .github
    cat > .github/CODEOWNERS << 'EOF'
    # Example: require review from core maintainers for critical paths
    /                           @org/legacyerp-core
    EOF
    git add .github/CODEOWNERS
    git commit -m "Add CODEOWNERS"
    git push
    

• GitLab:

  • Project > Members > Invite group/users with roles:
    • Maintainer (overall admin for project)
    • Developer (push to non-protected branches, create MRs)
    • Reporter/Guest as needed

• Bitbucket:

  • Repository settings > User and group access
  • Assign Admin/Write/Read permissions to groups and users accordingly

Recommended defaults:

• Admin/Maintainer: small set of leads
• Developer/Write: regular contributors
• Read/Reporter: stakeholders or CI-only accounts

6) Validation Test (End-to-End)

Perform the following to validate the workflow:

1. Clone test (fresh location):

cd /tmp
git clone git@github.com:ORG/LegacyERP-Core-System.git
cd LegacyERP-Core-System
git fetch --all --prune
git branch -r

2. Direct push to main is blocked:

git checkout -b dryrun-main-edit main
printf "\nValidation: %s\n" "$(date -u +%FT%TZ)" >> README.md
git add README.md
git commit -m "Validation: attempt direct commit to main"
git push origin HEAD:main
# Expected: push rejected due to branch protection

3. Feature branch and Pull/Merge Request:

git checkout develop
git pull
git checkout -b feature/validation
printf "\nFeature validation note\n" >> README.md
git add README.md
git commit -m "Add feature validation note"
git push -u origin feature/validation

• Open a Pull Request/Merge Request from feature/validation into develop.
• Approve and merge per the protection rules.
• After merge, update local:

git checkout develop
git pull

4. Release tagging:

git checkout main
git pull
git tag -a v0.1.0 -m "Initial baseline for LegacyERP Core System"
git push origin v0.1.0

5. Hotfix flow:

git checkout -b hotfix/0.1.1 v0.1.0
# Apply fix
git commit -am "Fix: critical issue in 0.1.0"
git push -u origin hotfix/0.1.1
# Open PR/MR into main; after merge, back-merge or cherry-pick into develop

6. Optional templates:

mkdir -p .github
cat > .github/pull_request_template.md << 'EOF'
Summary:
Changes:
Testing:
Checklist:
- [ ] Code builds
- [ ] Tests pass
- [ ] No secrets added
EOF

git add .github/pull_request_template.md
git commit -m "Add PR template"
git push

Verification Methods

• Confirm repository is accessible via SSH and clone works.
• Confirm main and develop are protected as configured.
• Confirm direct pushes to main are rejected.
• Confirm feature branch PR/MR flow completes successfully.
• Confirm tags push successfully and are visible in the platform’s releases/tags.
• Confirm team permissions operate as intended (Developer cannot push to protected branches).
• Confirm Git LFS (if enabled) tracks defined patterns and uploads large files.

Notes and Common Issues

• SSH “Permission denied (publickey)”:

  • Ensure the correct public key is added to the platform account.
  • Verify the SSH remote URL matches the platform.
  • Run: ssh -T git@ to confirm connectivity.

• Remote already exists or incorrect:

git remote -v
git remote set-url origin git@<host>:<OWNER>/<REPO>.git

• Line-ending issues across OS:

  • Windows: core.autocrlf true
  • macOS/Linux: core.autocrlf input
  • Re-commit changed files after updating settings.

• Large files and LFS:

  • Enable LFS before adding large binaries.
  • For existing large files already committed, consider history rewrite with a verified tool (e.g., git filter-repo). Rotate any affected secrets before publishing.

• Accidental secret commit:

  • Immediately rotate the secret at its source (API key/token/password).
  • Remove the secret from the repository and open a remediation PR.
  • If already pushed, remove from history using a verified rewrite tool and force-push only if branch protection allows or under admin procedure. Document the incident.

• Merge conflicts:

git fetch --all
git checkout feature/branch
git merge origin/develop  # or rebase if policy allows
# Resolve conflicts in files
git add <resolved files>
git commit
git push

• Safe update of default branch name:

# Local rename (if needed)
git branch -m master main
# Push and set upstream
git push -u origin main
# Update default branch in platform settings to 'main'

• Repository maintenance:
  • Use descriptive commit messages.
  • Keep feature branches short-lived.
  • Delete merged branches.
  • Avoid force pushes on shared branches.

This guide provides a complete, actionable setup for the LegacyERP Core System repository, from environment preparation to protected-branch collaboration and validation.