DEV Community: Brandon Pugh

Tips for creating merge commits

Brandon Pugh — Tue, 03 Sep 2024 17:01:55 +0000

I've reviewed quite a few pull requests in recent years and I've noticed some less-than-ideal practices when it comes to creating merge commits so I thought I'd list some things you can do to make life a little easier for someone reviewing your code.

Make the commit message as useful as possible

A lot has been written about how to write good commit messages, but I rarely see the advice applied to merge commits.
They may not be the most exciting type of commit, but they're still very important.

When merging PRs

Merge commits that merge a pull request are more straight forward because, these days, they're generally created by the git hosting service so you know they only contain all the changes from that feature branch.

But you can still make sure they convey the most useful info.
I like the default from Azure DevOps:

Merged PR 123: <PR title>

<PR Description>

You can get a similar defult in GitHub by configuring the default merge commit settings in the repository settings.

For other merge commits

Now, keep in mind that the need for other merge commits can be mitigated by keeping feature branches small and short-lived, but that's not the reality for a lot of teams.

For the most part I recommend sticking with the default message that git generates when you run git commit to complete a merge:

Merge branch 'main' into feature-branch
# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.

If you notice though, it includes a comment recommending explaining why the merge was necessary.
This could be something like "Merging in updated auth flow" or "Merging in changes to sharedService to avoid conflicts".
This also implies that you should have a reason for the merge which I agree with because otherwise you're adding unnecessary noise to the git log.

At the very least make it clear that it's a merge commit.
Don't just put something like update database migrations if you did have to do that as a result of the merge then mention it in the body of the message (though as I'll explain shortly, it should go in a followup commit).
Otherwise, depending on how you're viewing the git log, it might not be obvious that it's a merge commit.

List conflicts in the commit message

If there were conflicts during the merge, then git will list the files in the commit message, but they're commented out by default:

Merge branch 'main' into feature-branch

# Conflicts:
#   package.json
#   package-lock.json
#
# It looks like you may be committing a merge.
# If this is not correct, please run
#   git update-ref -d MERGE_HEAD
# and try again.

You can remove the # from the lines to uncomment them and include them in the commit message.

As a reviewer, I appreciate this because it's easy to make mistakes when resolving conflicts so if I see files listed then I can scrutinize them more closely.

You can make it even more convenient by using a prepare-commit-msg hook to uncomment them automatically:

COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

if [ "$COMMIT_SOURCE" = "merge" ]; then
    sed -i.bak '/^# Conflicts:/,/^#$/ s/..//' "$COMMIT_MSG_FILE"
fi

Bonus: use `git show --remerge-diff` to see how they were resolved

In Git 2.36, the --remerge-diff option was added to git show.
This makes it easier to see how conflicts were resolved in a merge commit.

Avoid "evil" merges

An "evil" merge as defined by the git docs is:

a merge that introduces changes that do not appear in any parent.

or as Linus himself puts it:

an "evil merge" is something that makes changes that came from neither side and aren't actually resolving a conflict

A merge commit is likely pulling in a large amount of unrelated changes, so it can be hard to notice if you add in your own changes.
I prefer to do the bare minimum to resolve any textual conflicts.

If there are semantic issues that need to be resolved (i.e. a database view was renamed so my code fails at runtime), then I fix them in a separate commit which not only makes it easier to review but also makes commands like git blame more useful.

Git Config Settings I Always Recommend

Brandon Pugh — Sun, 21 Jan 2024 06:16:28 +0000

Spanish translation

If you've ever worked on a project with me then I've probably recommended at least one of these config settings in git.

git config --global pull.rebase true - tells git to always pull with rebase instead of merge (the equivalent of pull --rebase). This not only saves you having to type the flag every time, but also ensures gui clients will also use rebase when pulling. Note: You should only enable this if you’re comfortable with rebasing.
git config --global fetch.prune true - tells git to automatically run git remote prune after a fetch. This will clean up any local objects that no longer exist on the remote like tracking branches that have been deleted from the remote server.
git config --global rebase.autoStash true - tells git to automatically stash when you perform a pull and then attempt to unstash them once the rebase is complete. This is almost always my workflow so it's nice to have git do it for me.
git config --global rebase.autosquash true - tells git to automatically include the --autosquash parameter when doing a git rebase --interactive. You should read more about autosquashing commits if you're unfamiliar with it. I use it all the time for fixing up or rewording previous commits.

Newer settings

If you haven't updated git in a couple years then you should as it's worth it just for these new config options.

git config --global push.useForceIfIncludes true (2.30.0) - This setting makes push --force-with-lease even safer. See the docs for more info.
git config --global push.autoSetupRemote true (2.37.0) - Git will automatically setup an upsteam tracking when you run git push from a new branch.
git config --global rebase.updateRefs true (2.38.0) - the --update-refs option makes working with stacked branches easier

Personal preference

You might find these useful depending on your personal workflow.

git config --global commit.verbose true - Git will include the diff of the changes at the bottom of the commit message template. I like this because your text editor can then autocomplete variable or function names you want to include in the commit message.
git config --global rerere.enabled true - It stands for Reuse Recorded Resolution, and tells Git to remember how you resolved a merge conflict and automatically reapply if it sees it again.

Blazor Best Practices Borrowed From React

Brandon Pugh — Tue, 21 Mar 2023 16:26:01 +0000

This article was originally published on https://www.brandonpugh.com/blog/blazor-best-practices/

Blazor took a lot of design decisions from React and other frontend frameworks and as a stateful component-based UI framework there is quite a bit of experience that can be transferred from one to the other.

I gave this talk earlier this year at KCDC and then last week I presented an updated version as a Jetbrains webinar. Special thanks to Khalid for inviting me on and being an excellent host!

I hope to write up the content in a more in depth post sometime soon, but in the mean time you can watch the recording on Youtube and view the slides at brandonpugh.com/blazor-talk.

Some of the points I cover:

State management
Reusable components
Accessibility
Testing

Blazor Best Practices Borrowed from React