If you're a developer, you probably use the versioning system called Git on a daily basis. The use of this tool is crucial for the development process of an application, whether working in a team or individually. However, it's common to encounter messy repositories, commits with unclear messages that don't convey useful information, and misuse of branches, among other issues. Knowing how to use Git correctly and following good practices is essential for those who want to excel in the job market.
Table of contents
- Naming Conventions for Git Branches
- Branch Names Convention Prefixes
- Commit Message
- Conventional Commit's
Naming Conventions for Git Branches
When we're working with code versioning, one of the main good practices that we should follow is using clear and descriptive names for branches, commits, pull requests, etc. Ensuring a concise workflow for all team members is essential. In addition to gaining productivity, documenting the development process of the project historically simplifies teamwork. By following these practices, you'll see benefits soon.
Based on it, the community created a branch naming convention that you can follow in your project. The use of the following items below is optional, but they can help improve your development skills.
1. Lowercase: Don't use uppercase letters in the branch name, stick to lowercase;
2. Hyphen separated: If your branch name consists of more than one word, separate them with a hyphen. following the kebab-case convention. Avoid PascalCase, camelCase, or snake_case;
3. (a-z, 0-9): Use only alphanumeric characters and hyphens in your branch name. Avoid any non-alphanumeric character;
4. Please, don't use continuous hyphens (--). This practice can be confusing. For example, if you have branch types (such as a feature, bugfix, hotfix, etc.), use a slash (/) instead;
5. Avoid ending your branch name with a hyphen. It does not make sense because a hyphen separates words, and there's no word to separate at the end;
6. This practice is the most important: Use descriptive, concise, and clear names that explain what was done on the branch;
Wrong branch names
fixSidebarfeature-new-sidebar-FeatureNewSidebarfeat_add_sidebar
Good branch names
- feature/new-sidebar
- add-new-sidebar
- hotfix/interval-query-param-on-get-historical-data
Branch Names Convention Prefixes
Sometimes the purpose of a branch isn't clear. It could be a new feature, a bug fix, documentation updates, or anything else. To address this, it's a common practice to use a prefix on the branch name to quickly explain the purpose of the branch.
feature: It conveys a new feature that will be developed. For example,
feature/add-filters;
release: Used to prepare a new release. The prefix
release/is commonly used to do tasks such as last touched and revisions before merging the new updates from the branch master to create a release. For example,release/v3.3.1-beta;
bugfix: It conveys that you're solving a bug in the code and it's usually related to an issue. For instance,
bugfix/sign-in-flow;
hotfix: Similar to bugfix, but it is related to fixing a critical bug present in the production environment. For example,
hotfix/cors-error;
docs: To write some documentation. For example,
docs/quick-start;
If you're working in a workflow with task management, like Jira, Trello, ClickUp, or any similar tool that can create User Stories, each card has a number associated. So, is commonly use these card numbers on the prefix of branch names. For example:
feature/T-531-add-sidebardocs/T-789-update-readmehotfix/T-142-security-path
Commit Message
Let's go talk about commit messages. Unfortunately, is so easy to find projects with commit messages like "added a lot of things" or "Pikachu, I choose you"... Yeah, I once found a project where the commit messages were related to a Pokémon fight.
Commit messages are really important in the development process. Creating a good history will help you a lot of times in your journey. Like branches, commits also have conventions created by the community, which you can learn about below:
A commit message has three important sections: Subject, Description, and Footer. The subject of a commit is required and defines the purpose of a commit. The description (body) is used to provide additional context and explanation for the commit's purpose. Lastly, there's the footer, commonly used for metadata like assigning a commit. While utilizing both the description and footer is considered a good practice, it's not required.
Use the imperative mood in the subject line. For example:
Add README.md✅;
Added README.md❌;
Adding README.md❌;
- Capitalize the first letter of the subject line. For example:
Add user authentication✅;
add user authentication❌;
- Don't end the subject line with a period. For example:
Update unit tests✅;
Update unit tests.❌;
Limit the subject line to 50 characters, i.e., be clear and concise;
Wrap the body at 72 characters and separate the subject from a blank line;
If your body of commit has more than one paragraph, so use blank lines to separate them;
If necessary, use bullet points instead of only paragraphs;
Conventional Commit's
"The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history."
The quote below was obtained from the Conventional Commit's official website. This specification is the most used convention to commit messages in the community.
Structure
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Commit Type
The first structure that we have to study is the commit type. It provides a clear context about what's done in this commit. Below you can see the list of commit types and when to use them:
feat: Introductions of new functionalities;
fix: Rectifications of software bugs;
refactor: Employed for code alterations preserving its overall functionality;
chore: Updates not impacting production code, involving tool, config, or library adjustments;
docs: Additions or modifications to documentation files;
perf: Code changes enhancing performance;
style: Adjustments related to code presentation, like formatting and whitespace;
test: Inclusion or correction of tests;
build: Modifications affecting the build system or external dependencies;
ci: Alterations to CI configuration files and scripts;
env: Describes adjustments or additions to configuration files within CI processes, such as container configuration parameters.
Scope
A scope is a structure that can be added after the commit's type to provide additional contextual information:
fix(ui): resolve issue with button alignmentfeat(auth): implement user authentication
Body
The body of a commit message provides detailed explanations about the changes introduced by the commit. It's typically added after a blank line following the subject line.
Example:
Add new functionality to handle user authentication.
This commit introduces a new module to manage user authentication. It includes
functions for user login, registration, and password recovery.
Footer
The footer of a commit message is used to provide additional information related to the commit. This can include details such as who reviewed or approved the changes.
Example:
Signed-off-by: John <john.doe@example.com>
Reviewed-by: Anthony <anthony@example.com>
Breaking Change
Indicate that the commit includes significant changes that may lead to compatibility issues or require modifications in dependent code. You can add a BREAKING CHANGE in the footer or include ! after the type/scope.
Examples of commits using conventional commits
chore: add commitlint and husky
chore(eslint): enforce the use of double quotes in JSX
refactor: type refactoring
feat: add axios and data handling
feat(page/home): create next routing
chore!: drop support for Node 18
With subject, body and footer:
feat: add function to convert colors in hexadecimal to rgba
Lorem Ipsum is simply dummy text of the printing and typesetting industry.
Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.
Reviewed-by: 2
Refs: #345
Top comments (48)
really nice article! I'm practicing these GIT standards actually, thanks for sharing! 😊
Good one!
This is a great summary! Thank you!!
Good one, Anthony! Thanks for sharing this with us. 🙌
Excellent article! Maintaining standardization in our daily lives is essential 😁
This whole debate is irrelevant, just use whatever you are comfortable with. Using Vim doesnt make you more efficient or productive. You know what makes you quicker and more productive? Knowing how to code...
A really nice article to read, it's worth it
These are great recommendations and resources! Thanks for putting this together!
One addition that we usually add is the commit message should include the work ticket number if you are using a ticketing system. This can be a huge help as it connects the commit to whatever additional details, resources, and conversations are associated with the ticket, and can be really helpful for understanding context when looking at old commits.
Gitflow is something that people barely talk about. Just spam "conventional commits" without showing practical examples is kinda useless.
Really great article, loved how you explained these topics :D
Using Conventional Commits everything in commit title goes in lower-case?
Yes! lower-case and hyphen to separate
Thank you for reply, Anthony :)
A nice feature of the
/separator is that in many UI interfaces will use that to infer a directory structure.Adding to the bit about including Jira issue keys, including them in your commit message will auto-link them in BitBucket (e.g.
git commit -m "Refactor LoginDialog" -m "WTM-305")This is great, I generally try to use these conventions on the projects I'm on—however, I've never heard of the commit type. Personally, I think it's unnecessary and adds more overhead than needed—the subject itself should be enough. If your commits are part of a PR, then the PR title should already be descriptive enough to encapsulate the general category of commits.
Insightful post 🔥 @anthonyvii
Even I used to do conventional commits before but when I realised that few practices can level up you as a Developer, I started using standard commits that made other developers in my team feel overwhelmed.
Remember, you are not alone coding the entire project in any organisation. Maintaining standards in your code helps maintain readability, contextual awareness and effecient collaboration.
I just started to apply them. I am happy to see that I am on the right path. However, I had the feeling that at sometimes it feels limiting. I struggled finding the right words. Could also be me of course..
Some comments may only be visible to logged-in visitors. Sign in to view all comments.