Developer Git Commit Hygiene

gowebing

Maintaining good commit hygiene is crucial for keeping your Git repository clean, manageable, and understandable for everyone involved in the project. 

Here are some best practices for ensuring good commit hygiene as a Java developer.

Git Hygiene Best Practices

1. Meaningful Commit Messages

Write Clear and Descriptive Messages

Each commit message should clearly describe what the commit does: 

Example: 
  

   Add user authentication module - Implement login and logout functionality - Add JWT-based authentication - Update user model to include hashed passwords - Add unit tests for authentication logic


Use the Imperative Mood

Start commit messages with a verb in the imperative mood (e.g., "Add", "Fix", "Update").

2. Small, Atomic Commits

Commit Small Changes

Make each commit a small, self-contained change that addresses a single issue or feature. This makes it easier to review and debug.

Avoid Large Commits

Large commits are harder to review and understand. Break down large changes into smaller, logical commits.

3. Commit Often, but Not Too Often

Frequent Commits

Commit frequently to save your progress and reduce the risk of losing work.

Avoid Noise

Don't commit excessively small changes that don't add meaningful value.

4. Separate Concerns

One Purpose Per Commit

Each commit should have a single purpose. Avoid mixing unrelated changes in a single commit.

5. Test Before Committing

Run Tests

Ensure all tests pass before committing. This prevents broken commits from entering the codebase.

Code Quality Checks

Use static analysis tools (e.g., Checkstyle, PMD) to ensure code quality before committing.

6. Use Branches Effectively

Feature Branches

Develop new features and bug fixes in separate branches rather than directly on the main branch.

Branch Naming

Use descriptive branch names (e.g., feature/add-authentication).

7. Rebase and Squash Commits

Rebase Instead of Merge

Use git rebase to keep a linear history and avoid unnecessary merge commits.

Squash Commits

Combine multiple small commits into one meaningful commit before merging to the main branch.

8. Avoid Committing Generated Files

Git Ignore

Use a .git ignore file to prevent committing generated files, build artifacts, and other unnecessary files.

Example:

  

   # Compiled class files *.class # Log files *.log # Build directories /target/


9. Document Important Changes

Commit Message Body

Provide additional context in the commit message body if the change is complex or requires explanation.

Example: 
  

   Refactor authentication module - Simplify token validation logic - Improve error handling in login process - Update documentation for the new authentication flow


10. Review Commits Before Pushing

Interactive Rebase

Use interactive rebase (git rebase -i) to review and clean up your commits before pushing.

Amend Last Commit

If you need to make small changes to the last commit, use git commit --amend.

Example of a Good Commit Workflow

1. Stage Changes

  

   git add .


2. Commit With a Descriptive Message

  

   git commit -m "Add user authentication module"


3. Review Commits

  

   git log


4. Rebase and Squash Commits if Necessary

  

   git rebase -i HEAD~N


5. Push To Remote Repository

  

   git push origin feature/add-authentication


Example of a Good Commit Workflow

Git Commit Cheat Sheet

Here is a cheat sheet for quick reference to Git commands (source: GitLab).

Git Configuration

git config --global user.name “Your Name”
Set the name that will be attached to your commits and tags.
git config --global user.email “you@example. com”
Set the e-mail address that will be attached to your commits and tags.
git config --global color.ui auto
Enable some colorization of Git output.

Starting a Project

git init [project name]
Create a new local repository in the current directory. If [project name] is provided, Git will create a new directory named [project name] and will initialize a repository inside it.
git clone <Project URL>
Downloads a project with the entire history from the remote repository

Day-To-Day Work

git status
Displays the status of your working directory; Options include new, staged, and modified files. It will retrieve branch name, current commit identifier, and changes pending commit.
git add [file]
Add a file to the staging area. Use in place of the full file path to add all changed files from the current directory down into the directory tree.
git diff [file]
Show changes between working directory and staging area
git diff --staged [file]
Shows any changes between the staging area and the repository
git checkout -- [file]
Discard changes in working directory; This operation is unrecoverable.
git reset <path>...]
Revert some paths in the index (or the whole index) to their state in HEAD.
git commit
Create a new commit from changes added to the staging area. The commit must have a message.
git rm [file]
Remove file from working directory and staging area.

Storing Your Work

git stash
Put current changes in your working directory into stash for later use.
git stash pop
Apply stored stash content into working directory, and clear stash.
git stash drop
Delete a specific stash from all your previous stashes.

Git Branching Model

git branch [-a]
List all local branches in repository. With -a: show all branches (with remote)
git branch [branch_name]
Create new branch, referencing the current HEAD.
git rebase [branch_name]
Apply commits of the current working branch and apply them to the HEAD of [branch] to make the history of your branch more linear.
git checkout [-b] [branch_name]
Switch working directory to the specified branch. With -b: Git will create the specified branch if it does not exist.
git merge [branch_name]
Join specified [branch_name] branch into your current branch (the one you are on currently)
git branch -d [branch_ name]
Remove selected branch, if it is already merged into any other. - D instead of -d forces deletion.

Tagging Commits

git tag
List all tags
git tag [name] [commit sha]
Create a tag reference named name for current commit. Add commit sha to tag a specific commit instead of current one.
git tag -a [name] [commit sha]
Create a tag object named name for current commit
git tag -d [name]
Remove a tag from local repository.

Synchronizing Repositories

git fetch [remote]
Fetch changes from the remote, but not update tracking branches.
git fetch --prune [remote]
Delete remote Refs that were removed from the remote repository.
git pull [remote]
Fetch changes from the remote and merge current branch with its upstream.
git push [--tags] [remote]
Push local changes to the remote. Use --tags to push tags.
git push -u [remote] [branch]
Push local branch to remote repository. Set its copy as an upstream.

Inspect History

git log [-n count]
List commit history of current branch. -n count limits list to last n commits
git log --oneline --graph --decorate
An overview with reference labels and history graph; One commit per line
git log ref .
List commits that are present on the current branch and not merged into ref; A ref can be a branch name or a tag name.

Reverting Changes

git reset [--hard] [target reference]
Switches the current branch to the target reference, leaving a difference as an uncommitted change. When --hard is used, all changes are discarded. It's easy to lose uncommitted changes with --hard.
git revert [commit sha]
Create a new commit, reverting changes from the specified commit. It generates an inversion of changes.

Final Thoughts

By following these practices, you can ensure good commit hygiene, making your Git history more readable and maintainable for you and your team.

 

 

 

 

Top