I don’t think these tips have anything to do with improving workflow per se.
Every alias/setting listed comes by default with any decent git gui. Personally I recommend Fork because of how easy it is to stage only specific lines, making it easy to split commits into logical chunks rather than by line-position chunks while also showing the git commit graph.
Improving workflow itself comes down to writing your code in a way that’s easy to review.
You can achieve that by:
- committing to a branching standard (see: trunk-based-development, git-flow, etc…)
- committing to a commit message standard (see: https://cbea.ms/git-commit/)
- keeping the reviewer’s perspective in mind while coding (see: https://redd.one/blog/the-art-of-code-review)
- and only separating commits by logical concerns, not file-path concerns.
Some devs get confused by the last point, so without writing a code example, here’s the do’s-and-don’ts:
- Bad: Adding all changes made across the project in a single commit.
- Bad: Adding all changes made in a single file as one commit.
- Why this is bad: Commits should only include changes that are logically related. Committing the changes of two functions is fine when the changes are logically related to each other, but you shouldn’t also be committing your work-in-progress changes made to another unrelated function just because it’s in the same file.
- Instead: Stage only the two functions that are related to each other and commit that. Then you can keep working on the work-in-progress function until you’re either happy with the changes, or throwing away the changes. (If you don’t know how to stage individual lines of a file, look into using a git gui like Fork or Sourcetree)
- Bad: Formatting a file/function then changing the code inside that file/function.
- Why this is bad: Looking back at the diffs of these commits is tricky, because you need to spend more time figuring out which changes are formatting related and which changes are code related. This is especially prevalent on lines that have both changes in them.
- Instead: Format the function/file first and commit that, then make your changes to your file/function and commit that as a second commit.
- Bad: Merging or submitting a pull request to merge a branch, without first rebasing and reviewing the changes yourself.
- Why this is bad (1): Code review can have a lot of overhead waiting for back-and-forth responses. The closer your code is to already being perfect, the less back-and-forth you’ll need and the faster your code will be reviewed. You should always review your own code before submitting it because you’ll catch both the tiny issues which reduces all the back-and-forth, and you’ll already have the mental model of what the change is doing in your head so your code’s first reviewer doesn’t need to spend that initial time setting up that mental model first.
- Why this is bad (2): Rebasing is useful for two reasons. The first is that it can bring your changes closer to the current state of the project by simply rewinding your branches changes, pulling to the latest commit on the main branch, then replaying your changes. This will make the difference between the two branches smaller. Secondly, you’re given a second chance to go through your commits, reword your commit messages, reorder commits so related logic is closer together, and throw away any commits that change one thing only to have the change reverted back in the next commit. If you’re not rebasing then you’re just making your code harder to review. (if you don’t know how to rebase, again you should probably be using a git gui, see this example by gitkraken: https://youtu.be/JkpYvXdbnfQ?t=72)
committing to a commit message standard (see: https://cbea.ms/git-commit/)
I am almost giving up on this except for personal projects. I still use this as much as possible even in work projects. But most enterprise clients even the ones from US and UK don’t seem to care about this anymore.
It’s easy to mandate, the server has a githook that disallows any push that contains a commit that doesn’t follow the standard.
Anyone who makes a bunch of commits on their end, then tries to push them will see an error message returned by the server pointing them to the standard. They then just have to rename their commits through an interactive rebase and repush. Interactive rebase is stupidly easy with most git-guis and easy enough for terminal users who have forgotten the commands through a 30 second youtube short.
I would love to do this and I will explore this.
What I have most issue with is the imperative mood — So many devs (in one case a very well-spoken EM), just say Added so and so changes instead of Add so and so changes.
I would like to know if this type of thing can be detected in a githook. What I usually do is educate the team I lead, but it all breaks/becomes harder when we either join another team for a duration or some other teams’ senior devs join our team(s).
It’s pretty hard to teach what imperative mood is.
English is hard to lint, but not impossible. See the Vale linter (not to be confused with the vale language)
I would love to annoy some people with this. But seriously, thank you for the recommendation. This is incredible.
Better mention that this article is about gitlab, some tips works only with gitlab.
Thanks for pointing that out. It’s not only about GitLab, but it contains a few GitLab specific tips. The others are solid, though.