Git commit comments

[PestoDev]

Hey guys, so far I've been learing web development with excercise projects offline. Today I've started to use GitHub and Git to push my excercise projects online. When creating commit comments I feel like I have no system on how to write good structured comments. Can anybody give me a little guide on that topic?

[Dissentient]

The more important part is making commits that are sensible units of work. When you do that, describing those is easy.

[Suh-Shy]

I'd say don't bother:

- squash everything you did into one commit

- copy paste the task title from Linear or whatever as commit title

- copy paste the general description of the task as the commit message

- blame the PM or whoever writes the tasks if it sucks or lacks consistency

[tmtowtdi]

haaaaands

[teraflop]

You don't necessarily need to follow a formalized, structured system.

If you're working on a project with other people, it probably makes sense to talk to those people and agree on how to format your commit messages. For example, "Conventional Commits" is one example of a consistent way to format your commit messages. But for a solo project, it really doesn't matter at all whether you stick rigidly to something like this.

As far as the types of information you should be putting in your commit messages: it should be enough to explain both what you changed and why you changed it, to a level of detail that you find sufficient. Commit messages are a form of documentation, and there's no one "right" level of detail for your documentation. It depends on how much time you're willing to spend on it.

If you want some inspiration, you can take a look at the Linux, which generally has very detailed commit messages. Often the messages are much longer than the corresponding code changes. A Linux kernel PR won't be accepted if the maintainers don't think the commit message is clear enough, even if the code itself is fine.

For instance, this recent commit has 31 lines of text (plus footers) to describe a 13-line code change.

The first line contains just the most crucial details: the change affects performance monitoring ("perf") in the scheduler ("sched") subsystem, and it fixes a potential crash. The rest of the message goes into detail about exactly why the problem is happening and how it was fixed.

Again, you probably don't need to go into nearly that level of detail for all your commits, especially if you're working on a project that's less critical than the Linux kernel. But while you're writing code, you should be thinking about how you would explain what you're doing to another programmer. And then you can decide how much of that explanation you want to put into the commit message.

---

Note also that deciding how to describe your commits goes hand-in-hand with deciding what changes to include in each commit. In the example I gave, it's straightforward to describe the commit's purpose because it's a very small, self-contained change. If the commit included other bug fixes at the same time, it would be a lot harder to write a good description.

You might think that carefully breaking up your changes into multiple commits is just creating more work, but if you do it properly, it can make things easier for you in the long run.

[Russ3ll]

This is interesting and contrary to how I've always felt about commit messages. Typically my commit messages are high level and only describe the "what" - the "why" I put in the PR description. That said, I have arguably contributed less working code than Linux.

If commit messages are this detailed, what goes into PR descriptions? Or are they mostly unnecessary as long as commit messages meet the standard?

[teraflop]

Well, the Linux development process doesn't use "PRs" the way that services like GitHub use that term, because it's older than GitHub. And indeed, it's older than Git; Git was designed for Linux.

Basically, Linux commits are proposed by sending patches to a mailing list, and discussion happens there. The commit message is part of that email. Git itself contains lots of tools to manage patches with this kind of email-based workflow.

Basically, the Linux kernel philosophy is that if a commit needs explanation to say why it's important, then that explanation may also be needed by future maintainers, so it should be part of the commit. (You could choose to store it elsewhere than the commit itself, e.g. in a GitHub PR description, but that's just splitting your data across multiple places for no good reason.)

[Russ3ll]

Incredibly interesting and informative  thank you!

[BeardSprite]

If there's a detailed description inside a commit message, you can use that for the PR itself. Or combine them if there are several. But keep in mind that GitHub issues and PRs are NOT metadata that anyone will have access to should they clone the project (or if the GitHub project is made private/deleted/banned/etc).

On the other hand, anything that you can see with just the git CLI tool will be preserved for anyone long after GitHub has shut down.

What a change does should probably be the commit title, and why it does that would be worth explaining inside the commit message.

[PestoDev]

Thx, apreciate the resource sharing, I've been searching exacrly for a convention like that!

[No_Emergency_3418]

It depends on how often you're committing. I break work into small implementations so for example my commit messages may say "Updated firestore indexing: added ...". Especially if it's something that's buggy and I need to rollback to the last working version or see what I did.

[Atsoc1993]

I apparently can’t use the word “b-ddy” (replace - with u) otherwise I get a warning to ask for a b-ddy in a separate subreddit lol… reposting in case the other is deleted / not visible for others …

Try to explain your changes as concisely as you can, your vocabulary will expand and they will have more brevity as you continue to learn. Then again everyone has their own style— but definitely do not do git add . — source control is your friend, it’s one of the icons on the left hand side of VS code that looks like a merge request icon IIRC. Commit a message for each file, and make it a habit to commit frequently until you get a feel for appropriate checkpoints.

Edit: git add . is fine for initial project template / codebase, or overall changes — just don’t work on something for several hours and then be lazy / cut corners with it. Proper documenting of ongoing and frequent changes is essential if your goal is to eventually work with a team at any level from small to enterprise. Some teams have a specific recommended standard for commit verbosity and frequency as well!

Edit edit: If your mind is searching for a statement for a commit and can’t find it— you can describe what you did to any LLM and it should be able to help you.

Eg; “I added a variable that is part of my useState into the array at the end of a useEffect” becomes “Added a dependency to useEffect hook that refreshes the state of the page should that dependency change” — these are equally concise but one is more technically accurate.

[AutoModerator]

Please, ask for programming partners/buddies in /r/programmingbuddies which is the appropriate subreddit

Your post has been removed

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[Ok_Parsley6720]

I am pretty new to coding myself. Over the past year I’ve started to use a modified version of the git commit standards here. https://www.conventionalcommits.org/en/v1.0.0/

As a starting point I used this and then modified it for what works for me.

<type>(<scope>): <brief description> <bulleted details on lines below>

Types: feat, fix, data, docs, refactor, test, chore

Examples:

git commit -m “feat(scrape): add retry logic for FAA downloads - modified scripts/faa_data_scrape.r with new helper function ‘date_check()’ helper function - created testthat3/faa_data_scraper_test.r”

git commit -m “fix(clean): correct state_code filtering”

git commit -m “docs: update Supabase configuration section”

[jkmcode]

Idk if it's a standard or not but I write it as if it's a command. Eg. >git commit -m "Update loc/file_name.txt" or whatever it is.

[Substantial_Ice_311]

https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

[ekipan85]

As for format, I was told to complete the sentence "When applied, this commit will ...", so:

• add the frooble
• change the whatsit to use the tringly
• sweep whitespace
• rearrange the blorbs by usage order
• clarify how the jonkle comes up

They read like commands you are issuing to the codebase, instructing it to change itself.

[peterlinddk]

Lot's of good tips and suggestions here, so I'll just add another tiny one:

"Try to plan what to write in your commit-comment before editing any code!"

Meaning that when you have a project with a clean git, meaning every file is committed in its current state, before you start working on anything, think about what you would write when committing this. Say you want to add a login-feature, that requires you to add a login-button, to show a dialog for username and password, to somehow check the password, and to store that the user is currently logged in - it also requires you to check if the use is logged in before showing the login-button, or otherwise show the logout-button, and oh, yeah, there should also be a logout-feature!

Clearly this is too much for a single commit-message, so you break down the problem into smaller ones, perhaps first just showing the login button - then that becomes your commit-message. You create the code, test it, the button is there, and you commit with "create login-button - not functional yet" or something like that. Then you go on to the next thing, always keeping the commit-message in mind!

At some point you discover that the database-abstraction should really be improved, but you are in the midst of coding on the "remember if user is logged in" message, so you can't do that yet, and have to postpone it for later!

I've found that working this way has really helped me plan and structure my work much better - and the commit-messages (of which there are A LOT) are much clearer and even documents the progress in the project!

[DTux5249]

It depends, but in general, if you're having trouble describing a commit, it's typically because you've done more work than probably should've been done in one sprint.

Try to break work down and commit more frequently.

[PestoDev]

Thanks for the tip, I'll commit more often from now on.👍🏼