Become a master at Git with these 8 best practices: Set-up, commit messages, git workflow, tags, and shortcuts.
- Set up Git
- Associate your text editor with Git
- Work on one issue at a time
- Write clear commit messages
- Provide placeholders for files ignored by .gitignore
- Find your Git workflow
- Use version tags
- Become a Git master
Never used Git before? Get your hands dirty with this super newby-friendly Git tutorial: https://try.github.io
1. Set up Git
- Set your username
git config --global user.name "YOUR NAME"
git config --global user.name
Source: Set your username in Git
- Set your email address
git config --global user.email "firstname.lastname@example.org"
git config --global user.email
Source: Set your email in Git
- Make sure that line endings are configured correctly
git config --global core.autocrlf input(Linux, OS X)
git config --global core.autocrlf true(on Windows)
Source: Handle line endings in Git
2. Associate your text editor with Git
If you are using Atom, you can quickly tell Git to use Atom for commit messages.
$ git config --global core.editor "atom --wait"
For other editors and more info, see associating text editors with Git.
3. Work on one issue at a time
Each change, addition, or removal you make to your code (adding a controller, modifying a model) should go into its own commit with its own clear commit message. The only exception is if two pieces of code are very closely related and updating both at the same is the only thing that makes sense. For example, if your code would otherwise break.
Working (and committing) one issue at a time will make it possible for others to understand what is going on. And make it much easier to fix bugs later.
With Git, it’s easy to explicitly review what you are about to commit:
git add --patchto add changes to the index
git diff --cachedto do a review of what you are about to commit
git committo execute the commit (this will open your editor for you to write a clear commit message!)
- Repeat from step 1 until you have committed everything (or the remaining uncommitted changes need further work).
4. Write clear commit messages
- Every commit message should consist of a subject line and a body
- Line 1: Subject line
- Use imperative tense for the subject line: “Fix bug”, not “Fixed bug”
- Limit to 50 characters
- Capitalize the first word
- No full stop at the end
- Line 2: Blank line
- Line 3+: Body
- Use imperative, present tense: “Change”, not “Changed” or “Changes”
- Limit each line to 72 characters
- Include motivation for the change and contrast its implementation to the previous behavior (what and why, rather than how)
Here is an example from chris.beams.io](http://chris.beams.io/posts/git-commit/)
Summarize changes in around 50 characters or less More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of the commit and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like ``log``, ``shortlog`` and ``rebase`` can get confused if you run the two together. Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that). Are there side effects or other unintuitive consequences of this change? Here's the place to explain them. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here If you use an issue tracker, put references to them at the bottom, like this: Resolves: #123 See also: #456, #789`
Why use the imperative tense? Because when someone is about to apply your commits to their code, it will tell them what your commits will do rather than telling them what they did. Moreover, it also matches Git-generated messages such as ‘Merge’ and ‘Rebase’.
Why add a short, descriptive subject line? Because it will allow people to
skim through your commits using
git log --oneline and quickly find the
commit that they are searching for.
Pro Tip 1: Sometimes subject-only commit messages are sufficient. In those
cases you can use
git commit -m "Your 50-character commit message" to
write a commit without using any text editor.
Pro Tip 2: You can amend an unpublished commit message by typing
git commit --amend (more on that here)
5. Provide placeholders for files ignored by .gitignore
This allows the user to get started with your project more quickly. They can just rename or reconfigure a few sample placeholder files, rather than manually digging through your code to see what files and variables they need.
If, for example, you are using the Rails Dotenv gem, you may want to provide
.env.example that is checked into source control. This should list
all the environment variables that can be defined and provides explanations
Minimize ignored files crucial for operation. Try to keep the count of ignored files, that a user will need to execute your project locally, to a minimum.
6. Find your Git workflow
There is no one way to use Git for your project. Your usage will depend on whether you are developing on your own, in a small team, or in a large open source project.
Generally, it is agreed that the master branch should always be ready for deployment. That means that development does not happen on that branch itself.
Instead, create a branch called
development that reflects the new code being
git checkout -b development
Even now, committing directly to the development branch should be avoided.
Instead, create a new branch from the development branch for new features
and bug fixed. Assign them a name that clearly summarizes the feature or bug fix
that you are working on. Examples are
$ git checkout development $ git branch email-notifications $ git checkout email-notifications
When we merge a new feature into our development branch, there are two scenarios to consider:
We have only made minor modifications, so we do not need to keep a separate history of the branch (scenario #1)
We have developed a full new feature, so we do want to keep a history of this branch in its entirety (scenario #2)
Scenario #1: Fast forward
Minor modifications are bug fix, spelling mistakes, and other changes affecting just a few lines of codes. There is no change in functionality or design.
--ff-only option forces a fast forward, so that your new branch won’t
clutter the git history. But in order for the fast forward to succeed, you first
need to rebase your branch to point to the most recent version of the
$ git rebase development YOUR_BRANCH_NAME $ git checkout development $ git merge YOUR_BRANCH_NAME --ff-only
Scenario #2: True Merge
New features are substantial changes that introduce new functionality, capabilities, or design to a project.
--no-ff option forces a true merge, retaining the separate branch history.
$ git checkout development $ git merge YOUR_BRANCH_NAME --no-ff
Workflow: Additional Resources
- I am working on two new blog posts: One on Solo Git Workflow and one on Team Git Workflow. Stay tuned!
- Read more about Git workflow on Github.
- Here is an absolutely excellent article on Git workflow using master, development, release, hotfix, and feature branches.
- See this great article by Christophe Porteneuve on when to merge and when to rebase.
7. Use version tags
Tags are mostly used to specify version numbers that go along with your code.
To add a basic tag to your last commit, do this:
$ git tag v1.4.3 # Tags the last commit with 'v1.4.3'
You can also create an annotated tag using:
$ git tag -a v1.4.3 # Opens the editor to allow you to create a message to go with your tag
To tag a past commit, specify the commit checksum:
$ git log --oneline # c6798fe Add Projects to Blog (PR #11) # ccf9022 Add projects layout file, Green Naropa project, and images # d39c2f6 Add collection of type 'project' # ece9068 Exclude canonical tag from HTML Proofer # 97655a4 Update site's url to www.finnwoelm.com # ... $ git tag v1.2.0 c6798fe # Adds tag v1.2.0 to commit c6798fe (Add Projects to Blog (PR #11))
Tags are not automatically pushed to Github. To push tags, do
To list all tags, do
git tag or filter tags with
git tag -l some_search_query.
Accidentally added the wrong tag?
Rename a tag using:
$ git tag new_tag tags/old_tag # Creates a new tag for the same commit as old tag $ git tag -d tags/old # Deletes the old tag
If you already pushed the old tag to Github, no problem. Use these commands to remove the old tag and push the new one:
$ git push origin :old_tag # Removes the old tag from Github $ git push --tags # Pushes the new tag to Github
8. Become a Git master
Github has a handy two-page cheat sheet with the most common Git commands: Git Cheat Sheet
Here are some additional commands:
git log branch_a...branch_b: lists all commits since branch_b split off branch_a. For example:
git log master...development. If branch_b is omitted, simply show all commits since branch_a.
git log --oneline: lists a log of past commits, showing only their first lines
git log -some_number: limit the log to some number of past commits. For example:
git log -2will only show the log for the last two commits.
git log -p: Go through the past commits and show changes made.
- Learn more formatting options for viewing the Git commit history.
git log --pretty=format:"%h - %an, %ar : %s"to show date and author name of each commit?
Featured Image Credits: Git Logo by Jason Long is licensed under the Creative Commons Attribution 3.0 Unported License.