Git Commit Tutorial: How to Track and Document Code Changes

Git has become the go-to system for managing changes to codebases. One of the most critical commands in Git is git commit, which captures a snapshot of your project's history at a specific point in time.

Understanding how to use git commit efficiently is crucial for maintaining a clean and organized project history. Writing meaningful commit messages and following best practices ensures that your repository remains manageable, whether you're working solo or as part of a larger team. 

This tutorial aims to teach you how to use the git commit command, write clear and informative commit messages, and adopt best practices for successful version control.

Let’s get into it!

What is a Git Commit?

One of the most fundamental building blocks of version control in Git is the git commit command. A git commit captures a snapshot of the current state of your staged files and saves them to the repository’s history. It creates a unique identifier for the changes and logs essential metadata, such as the author, timestamp, and a descriptive commit message—this ensures the modifications can be tracked, understood, and reverted if necessary. 

Developers can also add a commit message, which briefly describes the changes made and provides context and reasoning behind the update.

Essentially, commits are important because they allow developers to:

• Track changes: Commits provide a clear log of the modifications made to the codebase over time.
• Collaborate: In a team setting, commits help developers understand what changes were made, by whom, and why.
• Revert to previous states: If a bug or issue arises, commits allow developers to roll back the project to a stable point before the problematic change was introduced.
• Maintain a clean history: Structured, frequent commits with meaningful messages make managing large projects and diagnosing issues easier.

> If you're just getting started with Git and GitHub, the GitHub Foundations track offers a curated path to help you master the essentials of version control and collaboration workflows.

Basic Syntax of Git Commit

To use Git effectively, you must understand the basic syntax and structure of commits. This section walks through the core components of the commit process to ensure changes are captured and documented correctly.

Basic command

The simplest way to create a commit is by using the following command: 

git commit -m “Your commit message” 

Here, the -m flag allows you to include a short commit message describing the changes. This is where you provide context for future reference and collaboration, for example: 

git commit -m “Fix bug in user authentication” 

This command stages the commit and associates it with the provided message. 

What happens during a commit

Here’s what’s happening under the hood when you make a commit: 

1. Staging changes: Before committing, you must stage the changes using the git add command. This prepares the modified files for inclusion in the next commit. You can stage individual files or all modified files. 

git add file.txt  #Stages one file
git add .  #Stages all files in the current directory

2. Making the commit: Once your changes are staged, the git commit command takes the snapshot of the staged files and stores them in the repository. Note the snapshot is the current state of the files at the moment.
3. Updating the repository: After committing, Git updates the project’s history to save the commit alongside all the previous commits. Each commit acts as a checkpoint that can be rolled back if needed.

Writing Effective Git Commit Messages

Writing clear and meaningful commit messages is essential to maintaining a clean and understandable project history. A well-written commit message also serves as a communication tool, helping developers and collaborators quickly grasp each change's purpose and context.

Importance of good commit messages

Good commit messages act as a map. They provide insight into the reasoning behind each change, which becomes invaluable when reviewing the code later or troubleshooting issues. Well-written commit messages also make it easier to trace bugs, understand the evolution of features, and navigate through the repository’s history. 

Best practices for commit messages

To ensure your commit messages serve their purpose, follow these best practices:

1. Be descriptive: A commit message should explain what was changed and, when relevant, why the change was made. Avoid vague or generic messages like "fix" or "update." Instead, aim for specificity. For example, “Fix login form validation error” is much more helpful than simply “Bug fix.”
2. Use present tense: Commit messages should be written in the present tense. This gives the impression that you're describing what the commit is doing at that moment. For example, use "Add login validation" instead of "Added login validation."
3. Keep it short and simple: A concise message is more readable. The summary (the first line of the commit message) should typically be 50-72 characters, and if more explanation is needed, you can include a longer description in subsequent lines. This approach ensures the message can be easily viewed using various Git tools and interfaces.
4. Use bullet points for detailed changes: If your commit involves multiple related changes, use bullet points in the extended description to break down what was done. This helps create a clear structure, making it easier to follow.

> If you want to go beyond the basics of commits, the Intermediate Git course walks through more advanced concepts like amend, rebase, and managing commit history in teams.

Advanced Git Commit Options

The -m flag is a common option used in git commit commands, and it’s sufficient for daily usage. However, several other advanced options provide greater flexibility and efficiency when managing changes. In this section, we will take a look at those options. 

Commit without staging

In many cases, manually staging files with git add before committing may feel unnecessary, particularly when all modified files must be committed. To speed up this process, Git provides the -a flag, which stages all tracked files and commits them in one step. This means that any changes made to previously tracked files are included in the commit without having to run git add explicitly.

Here’s how it works:

git commit -a -m “Your commit message” 

Amend a commit

Mistakes can happen. Sometimes, you may need to change a commit you just made. The --amend option lets you modify the most recent commit instead of creating a new one. This allows you to update the commit message or add additional files to the same commit.

For example, to fix that last commit’s message: 

git commit --amend -m "Update commit message"

Or, if you forgot to stage a file, first add the file, then amend the commit:

git add missed-file.txt
git commit --amend

This effectively replaces the previous commit with the updated one. 

Note that amending should only be done on commits that haven’t been shared with others (e.g., not pushed to a shared repository) to avoid rewriting history that others might depend on!

Commit with changes and files from a specific commit

Sometimes, you need to correct or fix an issue in a previous commit without making unrelated changes. Git offers a --fixup option, which helps create a follow-up commit specifically linked to an earlier one. This is particularly useful when you need to clean up your commit history before merging your changes.

For example, to create a fixup for a specific commit:

git commit --fixup <commit-hash>

This command will create a new commit that is intended to address issues in the specified commit. 

Later, when you perform an interactive rebase, Git can automatically squash these fixup commits with the original commit they reference.

> For more advanced workflows like squashing commits, you can follow our detailed walkthrough in the Git Squash Commits tutorial.

Managing Commits with Git

As your project evolves and the commit history grows, managing commits becomes a critical aspect of maintaining an organized and navigable repository. Effective commit management helps with debugging, collaboration, and keeping a clean, comprehensible history. 

Git provides powerful tools that allow you to view the history of commits and revise or even undo changes when necessary. Knowing how to manage these commits can save significant time when resolving issues or refining your project’s history.

Viewing commit history

A crucial aspect of commit management is understanding the project’s history. The git log command allows you to view a detailed history of your commits. For context, it provides insights into when changes were made, who made them, and what messages were attached.

For example, here’s the basic git log command:

git log

This displays commit hashes, author names, dates, and commit messages. 

But Git also allows you to customize the log output to meet specific needs. For example, you can limit the number of commits displayed as follows: 

git log -n 5 # shows the last 5 commits

To inspect the changes made in each commit, use the -p flag, which shows the diff for each commit. 

Here’s how it looks:

git log -p

Reverting or undoing a commit

Sometimes, you need to backtrack or undo changes. One safe way to undo a commit is by using the git revert command. This creates a new commit that undoes the changes introduced by a previous commit without altering the commit history. 

This is especially useful when you’ve already shared commits with others and want to keep the history intact.

To revert a commit, use the following:

git revert <commit-hash>

This command applies an inverse of the specified commit’s changes, effectively undoing them while maintaining a transparent history.

Resetting a commit

In some cases, you may want to completely reset your repository to a previous state, erasing one or more commits. The git reset command allows you to do just that. However, resetting a commit modifies the commit history, so it should be used with caution, especially if the changes have already been pushed to a shared repository.

Git reset offers three modes:

1. Soft reset: Moves the commit pointer back to a specified commit but keeps the changes in the working directory and the staging area. This is useful when you want to redo a commit but preserve your changes. 

git reset --soft <commit-hash>

2. Mixed reset: Moves the commit pointer back to a specified commit and keeps changes in the working directory, but clears the staging area. This is Git’s default reset mode.

git reset --mixed <commit-hash>

3. Hard reset: Moves the commit pointer back to a specified commit and discards all changes in both the working directory and the staging area. This essentially reverts your repository to the state of the chosen commit and deletes any changes made after the commit. 

git reset --hard <commit-hash>

The git reset command is a powerful tool, but it’s essential to understand its implications (especially when working in a collaborative environment).  

Best Practices for Committing in Git

Effective version control requires more than just knowing Git commands – it also means following certain best practices to maintain a clean, comprehensible, and efficient project history. These practices not only help you manage your own work but also make it easier for collaborators to contribute and review changes.

Commit frequently, but keep it small

A good rule of thumb is to commit early and often, but to keep each commit small and focused. This approach ensures that each commit represents a distinct and logical unit of work. 

Committing frequently can help break large changes into manageable pieces, which makes it easier to review, test, and trace the evolution of your project. By committing smaller, isolated changes, you also reduce the risk of introducing complex errors. If something does go wrong, it’s easier to isolate and fix the problem when the commits are granular.

Commit only related changes

Each commit should be focused on a single task or issue. Mixing unrelated changes in one commit makes it harder to review and understand the intent behind the modifications. It also complicates the process of reverting or cherry-picking specific changes if needed.

For example, if you're working on a feature but notice a minor bug elsewhere in the code, it's better to handle those as two separate commits. This allows for a clear understanding of what was done and why – it also ensures that each commit is meaningful and isolated.

Collaborate with others on commit history

When working in a team, aligning with your collaborators on how commits are handled and presented is essential. This includes agreeing on a consistent format for commit messages and seeing to it that everyone follows best practices. Git hooks, such as pre-commit hooks, can help enforce rules like commit message formats or running tests before a commit is allowed.

Collaboration is also enhanced by tools that help manage and review commits, such as code review platforms like GitHub or GitLab. A clear, well-documented commit history makes it easier for team members to understand changes, discuss improvements, and keep the project moving forward efficiently.

> Want to tidy up leftover files before committing? Learn how to use git clean in this tutorial on removing untracked files.

Troubleshooting Common Git Commit Issues

Git commits can sometimes result in errors or challenges that may slow down your workflow. Understanding how to troubleshoot these common issues is crucial to maintaining smooth version control and avoiding more significant problems down the line.

Commit message errors

One common mistake when committing changes is forgetting to add a commit message or accidentally using a vague or empty message. Clear and informative commit messages are essential for keeping track of changes and allowing collaborators to understand the history of a project. Git will typically prevent you from committing without a message, but it's still possible to overlook the quality of the message itself.

Solution: Always double-check your commit message before hitting enter. If you accidentally submit a commit with an empty or unclear message, you can fix it using the git commit --amend command to modify the most recent commit message. 

Conflicts after commit

Conflicts are inevitable when multiple people are working on the same project. They often arise after a commit when you're merging branches or rebasing. A conflict happens when Git cannot automatically resolve differences between two commits, leaving you to manually choose which changes to keep.

Conflicts are most likely to occur when two or more contributors modify the same section of code or when large refactors are made to a project. While they can be daunting, Git provides the tools to resolve these conflicts without losing data.

Solution: When a conflict occurs, Git will mark the conflicting sections in the files, and you will need to manually resolve them by editing the file to reflect the desired changes. After making the necessary changes, stage the file with git add, then complete the merge or rebase by committing the resolved changes. Tools like Git's merge conflict editor or external merge tools can also help you resolve conflicts more efficiently.

Conclusion

The git commit command is a foundational aspect of version control in Git that allows developers to create snapshots of their work that can be tracked, reviewed and revisited over time. Commits serve as milestones in a project's history, clarifying what changes were made, why they were necessary, and when they were implemented.

In this tutorial, we covered the basic syntax and process of making a commit, from staging files with git add to finalizing the commit with git commit. We discussed the importance of writing clear and concise commit messages, following best practices like keeping messages descriptive, using the present tense, and maintaining brevity. 

Additionally, we explored advanced options, such as committing without staging and amending commits, offering flexibility when managing your changes. We also looked at how to manage commits through commands like git log, reverting, and resetting.

Ready to explore GitHub in more depth? Our GitHub Concepts course dives into forks, branches, issues, and collaboration best practices. If you're preparing for a real-world workflow or interview, the Complete Git Cheat Sheet is a great reference to keep handy!