Skip to main content

Git Best Practices

This guide outlines best practices for using Git, focusing on repository creation, branching, commit messages, and tagging to help maintain a clean and understandable version history.

Repository Naming​

Choose a repository name that is descriptive and easy to work with.

ConventionRecommendationExample
CaseUse lowercase.my-awesome-project
SeparatorsUse hyphens (-).customer-order-service
LengthKeep names concise but descriptive.web-app
AvoidUnderscores (_) or capital letters.MyProject, my_project

Branch Naming​

Use clear and consistent branch names to clarify the purpose of each branch.

Branch Prefixes​

Categorize branches by their purpose using prefixes.

PrefixPurposeExample Branch Name
mainThe primary branch with stable code.main
developIntegration branch for new features.develop
feat/New feature development.feat/user-authentication
fix/Bug fixes.fix/login-form-bug
docs/Documentation changes.docs/update-readme
style/Code style and formatting changes.style/format-source-code
refactor/Code refactoring.refactor/cleanup-api
test/Adding or improving tests.test/add-user-tests
chore/Maintenance and other tasks.chore/update-dependencies

General Guidelines​

  • Be Descriptive: The branch name should clearly state its purpose.
  • Use Hyphens: Separate words with hyphens (-).
  • Reference Issues: If applicable, include the issue or ticket number (e.g., feat/PROJ-123-add-new-feature).

Commit Messages​

A clear, well-structured commit history is essential for project maintainability. Following the Conventional Commits specification creates a standardized history that is easy for both humans and machines to understand.

Commit Message Format​

<type>(<scope>): <subject>

<body>

<footer>

  • <type>: The type of change being committed.

    TypeDescriptionExample
    featA new feature.feat: add user profile page
    fixA bug fix.fix: correct login button alignment
    docsDocumentation only changes.docs: update installation guide
    styleChanges that do not affect the meaning of the code.style: format code with prettier
    refactorA code change that neither fixes a bug nor adds a feature.refactor: simplify user model
    perfA code change that improves performance.perf: optimize image loading
    testAdding missing tests or correcting existing tests.test: add tests for user API
    choreChanges to the build process or auxiliary tools.chore: update webpack config

  • <scope> (optional): A noun describing the part of the codebase affected by the change.

    ScopeDescriptionExample
    apiChanges related to the API layer.feat(api): add new user endpoint
    authChanges related to authentication.fix(auth): correct token refresh logic
    uiChanges to the user interface.feat(ui): implement dark mode toggle
    depsDependency updates.chore(deps): update react-router to v6

  • <subject>: A concise description of the change.

    • Use the imperative, present tense (e.g., "add" not "added").
    • Do not capitalize the first letter.
    • Do not add a period (.) at the end.

  • <body> (optional): A more detailed explanation of the change.

  • <footer> (optional): Contains information about breaking changes and issue references.

Tagging Best Practices​

Tags mark specific points in a repository's history, such as version releases.

Annotated vs. Lightweight Tags​

  • Lightweight Tags: A simple pointer to a specific commit.
  • Annotated Tags: Stored as full objects in the Git database, containing metadata such as the tagger's name, email, date, and a message.
tip

Always use annotated tags for releases, as they contain valuable metadata.

Creating an Annotated Tag​

Use the -a flag to create an annotated tag with a message. It is a common convention to use Semantic Versioning.

# Create an annotated tag with a message
git tag -a v1.0.0 -m "Release version 1.0.0"

Pushing Tags to Remote​

By default, git push does not push tags. You must push them explicitly.

# Push a single tag
git push origin v1.0.0

# Push all local tags
git push origin --tags

Managing Tags​

  • List Tags: 
    git tag
  • Delete a Local Tag: 
    git tag -d v1.0.0
  • Delete a Remote Tag: 
    git push --delete origin v1.0.0

References​