Guide to using Git for OCCT development

Table of Contents

• Overview
  • Purpose
  • Repository URL
  • Repository Content
  • Quick Rules
• Setting Up Git
  • Prerequisites
  • Authentication
  • Fork and Clone
• Development Workflow
  • Create a Branch
  • Make Changes
  • Commit
  • Push and Create a Pull Request
  • CI/CD and Review
  • Merge
  • Keep Your Fork Updated
• Rebasing
• Cleanup

Overview

Purpose

This document provides a practical introduction to Git for OCCT contributors. OCCT development is hosted on GitHub at https://github.com/Open-Cascade-SAS/OCCT.

For experienced Git users, sections 1 and 3 are sufficient to get started. Please also read the Contribution Workflow for the overall process.

Repository URL

The official OCCT Git repository:

https://github.com/Open-Cascade-SAS/OCCT

Clone via HTTPS:

git clone https://github.com/Open-Cascade-SAS/OCCT.git

Or via SSH:

git clone git@github.com:Open-Cascade-SAS/OCCT.git

Repository Content

• master branch: the current development version. Official releases are marked by tags.
• IR branch: the weekly integration branch where contributions are merged after review and CI/CD checks.
• Topic branches for feature development, bug fixes, and improvements.

Quick Rules

• Configure your Git user name and email so that commits are properly attributed:

  git config --global user.name "Your Full Name"
  git config --global user.email "your@email.com"

• Create a fork of the repository and push your branches to your fork.
• Submit changes via Pull Requests (PRs).
• Branches that pass review and CI/CD checks are merged by maintainers (typically squashed into a single commit per PR).

Setting Up Git

Prerequisites

• Install Git from https://git-scm.com/downloads
• On Windows, Git for Windows is recommended, optionally with TortoiseGit for GUI support.
• On Linux and macOS, use your system package manager or the Git packages recommended by your distribution.

• Configure your identity before creating commits:

  git config --global user.name "Your Full Name"
  git config --global user.email "your@email.com"

• On Windows, keep line endings predictable for cross-platform patches:

  git config --global core.autocrlf true
  git config --global core.safecrlf true

If you use TortoiseGit or another graphical client, configure the same user name, email address, and SSH client in that tool.

Authentication

GitHub supports both HTTPS and SSH remotes. HTTPS is usually the simplest option for cloning and pushing through Git Credential Manager. SSH is convenient when you already use SSH keys:

ssh-keygen -t ed25519 -C "your@email.com"

Add the generated public key to your GitHub account, then check access with:

ssh -T git@github.com

Fork and Clone

1. Fork the repository on GitHub: click Fork at https://github.com/Open-Cascade-SAS/OCCT

2. Clone your fork:

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

3. Add the upstream repository as a remote:

   git remote add upstream https://github.com/Open-Cascade-SAS/OCCT.git

Development Workflow

Create a Branch

Always create branches from an up-to-date master:

git checkout master
git pull upstream master
git checkout -b my-feature-branch

Use any descriptive name for your branch (e.g., fix-empty-shape-crash, step-ap242-ed4).

Make Changes

Develop your change, following OCCT Coding Rules. Format your code using clang-format with the configuration provided in the repository.

Commit

Commit your changes with a meaningful message:

git add .
git commit -m "Modeling - Fix crash in BRepAlgoAPI_Fuse on null shapes"

The first line should follow the Group - Summary format (see Contribution Workflow). Provide a detailed description in the commit body if needed.

Push and Create a Pull Request

Push your branch to your fork:

git push origin my-feature-branch

Then create a Pull Request on GitHub:

• Go to your fork on GitHub
• Click New Pull Request
• Set the base to Open-Cascade-SAS/OCCT/IR and compare to your branch
• Start with a Draft PR to indicate work in progress
• When ready, click Ready for Review

CI/CD and Review

The CI/CD pipeline runs automatically on every push:

• Build checks (Windows, Linux, macOS)
• Code style verification (clang-format)
• DRAW test suite

Results appear in the GitHub Actions tab of the PR.

A reviewer examines the changes and provides feedback as PR comments. Address feedback by pushing new commits to the same branch. CI/CD re-runs automatically.

Merge

Once approved and all checks pass, a maintainer merges the PR. PRs are typically squashed into a single commit on IR.

Keep Your Fork Updated

Regularly sync your fork with upstream:

git checkout master
git pull upstream master
git push origin master

Rebasing

If your branch falls behind IR, rebase it:

git checkout my-feature-branch
git pull --rebase upstream IR

If conflicts occur, resolve them manually, then:

git add .
git rebase --continue

After rebasing, force-push to your fork:

git push --force origin my-feature-branch

Note: Do not force-push if others are working on the same branch.

Cleanup

After your PR is merged, delete the local and remote branch:

git checkout IR
git branch -d my-feature-branch
git push origin --delete my-feature-branch

Regularly prune stale remote tracking branches:

git fetch --prune upstream