preface
This is probably the most common pattern of making a commit.
$ git add .
$ git commit -m 'feat: add a login feature'From the get-go, there are two possible problems with the commit (that leads to many more problems).
$ git add .does not specify the contents of commit. If we know what we are committing code by code, there is nothing wrong with it. However, the chances are, this is nothing more than a ‘auto-save’ button that works manually.
This defeats the purpose of using git and making a commit. Git is a tool that helps maintain version control system of the code. Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later (git-scm.com).
If each version (or patch) represents whatever we are working on at current stage, why commit when you can simply presscmd + sinstead?- Single-lined commit message using ‘git commit -m <message>’ is usually not enough to describe what, why, and how this commit is done. Having not enough space to describe the commit leads to shorter commit message that nobody including ‘future-self’ can’t event understand.
Also, writing short commit message aggravates the risk of making a huge commit that includes whatever we feel like to add. This behaviour does not help organizing tasks, and it will potentially lead to a serious risk of ruining the project.
These two risks can be mitigated with two easy-to-use git commands.
1. git add -p
To alleviate the first problem, simply changing . to -p will do. No jokes.
$ git add -pdiff --git a/nextjs/pages/index.tsx b/nextjs/pages/index.tsx
index 92f75f9..f8cbe84 100644
--- a/nextjs/pages/index.tsx
+++ b/nextjs/pages/index.tsx
@@ -6,7 +6,7 @@ import styles from "../styles/Home.module.css";
const Home: NextPage = () => {
return (
<div>
- <h1> git is so boring</h1> /* this line is to be removed */
+ <h1>git is so boring</h1> /* this line is to be added */
</div>
);
};
(1/1) Stage this hunk [y,n,q,a,d,e,?]?/* if you press '?', it will help you choose what you want to do like below */
y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
e - manually edit the current hunk
? - print help
This “patch” flag will guide you code by code to help you choose what to stage for the commit. There are a lot of situations where we just have to do multiple tasks at once. This does not mean commit has to happen at once. Being deliberate with each commit will ensure what is happening with the task and massively improve confidence of code.
Do not be afraid to use ‘?’ command. This is perhaps the only ‘kind’ part of git. There are definitely edge cases when you stage code by hunk, and choices provided by git will shine light on your terminal.
2. git commit
Instead of writing extra -m 'feat: add pepperoni pizza to my lunch list' , why not shorten it with git commit ? This leads to the following stage.
/* first line should be HEADER */
/* there SHOULD BE A BLANK SPACE between header and body */
/* followed by the blank line, this is BODY */
/* there SHOULD BE A BLANK SPACE between body and footer */
/* followed by the blank line, this is FOOTER */# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch master
# Your branch is ahead of 'origin/master' by 2 commits.
# (use "git push" to publish your local commits)
#
# Changes to be committed:
# modified: pages/index.tsx
#
~
~
Rules are simple:
- Git commit message is composed of three parts: header, body, footer. Each part is separated by a single space line.
- Header is mandatory. This is where we write our
-mgit message - Body is not mandatory, but please add the following if any:
- What is now different than before?
- What is the reason for the change?
- Is there anything to watch out for?
- Anything particularly remarkable about this commit? - Footer is also not mandatory, but please add the following if any:
- BREAKING CHANGES
- task or bug number to add
The benefit of writing a descriptive commit message is not only about documentation. Once again, having a descriptive commit message forces you think deeply about the task (or commit). As we often feel lost what we are actually trying to accomplish from writing code, this gives you some time to give you an anchor to lean on when you feel lost.
Good programming is not always about creating a blazingly-fast program with the cutting-edge technologies. It is also about building a code structure with low dependency and high cohesion that has a flexibility to adapt, and spending time to understand the problem and organize tasks along is perhaps one of the most sustainable way to maintain technologies.
References
Git for Professional Tutorial: https://youtu.be/Uszj_k0DGsg
About Version Control: https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
