Crafting Git Commit Messages with Cursor

git cursor ai
Published on 17 Oct 2024 and last updated on 25 Oct 2024

While human-crafted Git commit messages remain the gold standard, AI can significantly speed up the process of creating decent quality messages, especially for routine commits. Cursor offers a way to automate part of this process, potentially saving developers time without sacrificing too much quality.

This approach works best when the staged changes clearly reflect the commit’s content, the AI has access to the project’s full context, and the developer provides a concise explanation of the “why” behind the changes. Throughout this post, we’ll explore how to leverage these factors to get the most out of AI-assisted commit message generation.

At the time of writing (October 2024), this guide is based on Cursor version 0.42.3. Features and functionality may vary in other versions.

Why Cursor? #

You might wonder why this guide focuses specifically on Cursor IDE when the core AI functionality comes from models like Claude 3.5 Sonnet and GPT-4o. There are two main reasons:

  1. Personal preference: Cursor is currently my IDE of choice, as it is for many developers.
  2. Superior integration: Of the AI-assisted coding tools I’ve tried, Cursor is the best. Cursor offers a more integrated solution with seamless transitions between the coding window and the AI prompt, facilitated by numerous shortcuts. Additionally, Cursor’s “Apply” feature allows for direct application of changes without the need for copy/pasting, which is required in other tools like Codeium (my second favorite).

While the approach described in this guide could theoretically be applied with other AI assistants, Cursor’s unique features make the process particularly smooth and efficient.

Preparing Your Changes #

For the best results, I recommend using Sublime Merge, which in my opinion is the best GUI tool for Git. Sublime Merge allows you to stage changes line by line, by hunk, or by file in a very smooth and easy way, enabling you to create the cleanest Git commits possible.

Sublime Merge is developed by the same Australian team that builds Sublime Text. It’s incredibly fast compared to other popular tools that often use Electron, as Sublime Merge is written in C++. It follows the same “WinRAR” model for licensing - offering an unlimited trial period for those who want to try it before buying.

First, stage the changes you want to commit:

git add <files>

Or, for a more granular approach, use Sublime Merge to visually select and stage your changes.

Sending Changes to Cursor #

  1. Run the diff command in your terminal within Cursor:

    git --no-pager diff --cached
  2. Click on the command output in Cursor.
  3. Press Ctrl + Shift + L to add the diff directly to the AI chat sidebar.

For large diffs, save them to a file first:

git --no-pager diff --cached > staged_changes.diff

Then in the Cursor AI chat prompt, click the small “+” button or the “Add context” text next to it, and select staged_changes.diff to add it to the chat context.

Generating the Commit Message #

Use the following prompt to ask Cursor AI to generate a commit message:

Generate a complete Git commit message following the "Conventional Commits" specification.

Avoid obvious details, unnecessary explanations, and filler content.
 
Explanation: [Your explanation here]

It’s crucial to provide a brief explanation of why the changes were made. While the AI can analyze the diff to understand what changed, it can’t infer the reasoning behind the changes. Your explanation helps the AI write an adequate and meaningful commit message that captures not just what changed, but also why the changes were made.

For example:

Generate a complete Git commit message following the "Conventional Commits" specification.

Avoid obvious details, unnecessary explanations, and filler content.

Explanation: This change optimizes the database query to reduce load times on the user profile page.

Remember to review and, if necessary, edit the AI-generated commit message to ensure it accurately reflects your changes and intentions.

Optimizing AI Model Selection #

  • For simple diffs, use the cursor-small model to save on API calls.
  • For complex changes or if initial results are unsatisfactory, switch to more powerful models like Claude 3.5 Sonnet or GPT-4o.

Fine-tuning the Prompt #

Experiment with the prompt to get the level of detail you need. For example:

  • To encourage more detailed messages: Remove the “Avoid obvious details, unnecessary explanations, and filler content” instruction.
  • To focus on specific aspects: Add instructions like “Focus on the main feature changes” or “Highlight any breaking changes”.

A Word of Caution #

While the approach described in this post can be effective and helpful in many cases, it’s crucial to use this feature judiciously. As of now, AI is not yet at the level of human developers when it comes to understanding the full context and implications of code changes.

Overreliance on AI-generated commit messages without proper review can lead to a confusing or misleading Git history. Remember, sometimes no message is better than an incorrect or misleading one. Always review and edit the AI-generated output to ensure it accurately represents your changes.

A clean and accurate Git log is invaluable for both human developers working on the project and for future AI analysis. Until AI models become as proficient as mid-level developers (at least) in understanding code changes, we should use these tools as aids rather than replacements for human judgment.

Some reports suggest that AI might be introducing more bugs than benefits in many codebases. While the veracity of such claims is debatable, it underscores the need for caution. This principle extends to commit messages, which are crucial for understanding a project’s history and development.

Given that codebases are often not very verbose, and documentation can be lacking or poorly maintained, a good Git commit history serves as perfect documentation for understanding a project’s progress. Therefore, we should treat our Git commit history with the same care and attention we give to our codebase and documentation.

Who Can Benefit from This Feature? #

The AI-assisted commit message generation feature can be beneficial for different types of developers and teams:

  1. Senior Developers: This feature can be particularly useful for experienced developers who already master the art of writing good commit messages. It can help accelerate the process for commits with significant changes, especially for less critical updates that don’t warrant extensive time crafting a manual message.

  2. Junior and Mid-level Developers: Teams with a significant number of less experienced developers can benefit greatly from this feature. Junior and mid-level developers often struggle with crafting informative commit messages, sometimes resulting in vague or unhelpful entries. By having senior team members create a well-structured prompt, the entire team can maintain a more consistent and informative Git commit history.

  3. Team Leads: This feature can be a valuable tool for maintaining code quality and documentation standards across the team. By setting up good prompts and guidelines, team leads can ensure that even less experienced team members contribute meaningful commit messages.

However, it’s crucial to note that the effectiveness of this feature heavily depends on proper software development practices:

  • Use of Git GUI Tools: Advocating for the use of good Git GUI tools like Sublime Merge, especially for less experienced team members, is essential. These tools help developers visualize changes, making it easier to stage appropriate modifications and create clean, purposeful commits.

  • Clean Staging Practices: The AI can only be as helpful as the staged changes allow. It’s critical that developers understand how to stage changes properly, avoiding mixing unrelated changes or including files that shouldn’t be committed (such as binary files or local configuration files).

Without proper development practices in place, the chances of effectively using this feature diminish significantly. Therefore, teams should focus on establishing good Git workflows and staging practices alongside the introduction of AI-assisted commit message generation.

A Meta Note #

This blog post itself was written with the assistance of Cursor and the long-context chat model of Claude 3.5 Sonnet. We’re using AI to write about using AI - how meta is that?

In fact, many sources claim that a large proportion of internet content is already written with AI assistance. Some even predict that up to 90% of online content will be AI-generated by 2026 (though we should take such predictions with a grain of salt). So this post is certainly not alone in its AI origins - we’re just being upfront about it.

Oh, and if you spot any attempts at humor in this post, credit (or blame) the AI for those. The human author disclaims all responsibility for any jokes, puns, or witty remarks!

A Note on Feedback #

You may notice there’s no comment section below this post. While I don’t currently have a commenting system in place, I still value your feedback. If you have any important suggestions, corrections, or additions, please feel free to email me. You can use any email handler @[this site’s domain], as my site is configured to catch all emails.

For general discussions or less urgent matters, consider sharing this post on platforms like Reddit or your preferred social media. Your insights and opinions are welcome there, and it helps spread the word about these AI-assisted development techniques. You can also find and participate in the discussion on Hacker News.

Addressing Feedback (Updated 18/10/2024) #

After sharing this post on Reddit and Hacker News, I received a comment that I’d like to address. This feedback on Reddit by user u/Electronic-Pie-1879 raised an interesting point:

Not worth reading, folks. He's suggesting to generate a commit message in a complicated way, which isn't necessary.

  1. Add files as staged.
  2. Then run `git --no-pager diff --cached`, copy it from the terminal, and prompt it with: "Generate a complete Git commit message following the 'Conventional Commits' specification. Avoid obvious details, unnecessary explanations, and filler content.

But you can just use `@/diff` and select commit. Done. Without copy it from terminal and then into chat and then prompt it.

This feedback provides an opportunity to clarify some important points about the approach described in this post:

  1. The current version of Cursor (0.42.3 at the time of writing) only offers the command @Commit (Diff of Working State), which also requires a prompt to generate a decent commit message. This command operates on modified files, not staged changes.
  2. In real-world development scenarios, it’s common to have multiple modified files that shouldn’t all be part of the same commit. Typically, developers need to stage specific changes for a commit, leaving other modifications for later commits or discarding them entirely.
  3. The approach described in this post allows for more precise control over what goes into each commit message by focusing on staged changes rather than the entire working state. This aligns with best practices for creating clean, atomic commits.
  4. The need for commit messages based on staged changes (rather than the entire working state) is a common request in the Cursor community. You can find numerous discussions about this in Cursor’s official forums and GitHub issues, indicating that many developers share this workflow preference.
  5. While the process described here might initially seem more involved, it offers greater flexibility and precision in crafting commit messages. This is particularly valuable for complex changes or in projects with strict commit message guidelines.

I appreciate all feedback and will continue to update this post as new features become available or better methods are discovered. Ultimately, the goal is to balance the convenience of AI-assisted commit message generation with the need for precise, context-aware version control practices. As tools like Cursor continue to evolve, we may see even more streamlined ways to leverage AI effectively in the commit process while maintaining high standards for version control.

Conclusion #

By leveraging Cursor, you can quickly generate meaningful Git commit messages that follow best practices. This approach saves time and helps maintain a consistent commit history across your projects.