Knowledge Base

Git Workflow

2 min read

Git Workflow

Git Repositories are a versioned primitive for project files.

Repository Types

Git Repos can be used for:

  • Source Code
  • Documentation
  • Literature or Manuscripts
  • Notes and Knowledge Bases
  • Research Data (text-based or structured)
  • Configuration Files
  • Infrastructure as Code (IaC)
  • Legal Documents (Law)

Branching

The primary branch is main. Branches should be created freely as needed. Each feature, bug fix, experiment, or longer-running task should be developed in its own branch before being merged back into main. This keeps the main branch stable while enabling parallel work.

  • feature/: For new features
  • fix/: For bug fixes
  • docs/: For documentation-related changes
  • experiment/: For prototypes or exploratory ideas

Branch names should be short, descriptive, and hyphen-separated.

Pull Requests

When merging a branch into main, prefer using a Pull Request (PR):

  • Helps provide visibility
  • Ensures code review
  • Allows automated checks (tests, linting, CI) to run
  • Captures context for future reference

PRs should be:

  • Small and focused
  • Linked to issues or tasks when possible
  • Clearly titled and described

Conventional Commit Types

Conventional commits follow a structured format to communicate intent clearly:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes only
  • style: Non-functional changes (formatting, whitespace, etc.)
  • refactor: Code changes that neither fix bugs nor add features
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Changes to build system or dependencies
  • ci: Changes to CI configuration
  • chore: Routine tasks, maintenance, or repository housekeeping
  • revert: Reverting a previous commit

Each commit message should follow:

type(scope): short description

Releases

Releases provide stable, versioned snapshots of the repository. They allow users or systems to rely on specific, predictable versions. This can be done using cocogitto.

Use Semantic Versioning (SemVer):

  • MAJOR: Breaking changes
  • MINOR: New features that are backwards compatible
  • PATCH: Backwards-compatible bug fixes

Versions are annotated using Git tags, e.g.:

v1.4.2

GitOps

GitOps is the practice of managing automation workflows and CI/CD pipelines entirely through Git. Git serves as the single source of truth for any project. Any change to scripts, configuration, or automation is tracked in Git, and automated systems ensure the desired state is consistent. Multiple automation pipelines can respond to Git events to handle repetitive tasks, enforce checks, or trigger other processes.

Event Types

  • Push events: Trigger automated tasks when changes are committed.
  • Pull request events: Enable previews, testing, or review workflows.
  • Scheduled or manual events: Run tasks on demand or on a fixed schedule.

Graph View