Git: from beginner to advanced user

2019-09-12T00:00:00+00:00

A journey with Git command line.

Disclaimer</h2>
This article uses the Git command line exclusively.

The command line is the only place you can run all Git commands.</li>
If you know how to run the command-line version, you can figure out how to run the GUI version.</li>
Your choice of graphical client is a matter of personal taste; all users will have the command-line tools installed and available.</li> </ul>
Many users will use only a limited subset of Git commands, but don't forget that Git is still under active development. You can find all the changelogs on GitHub</a>.
Beginner</h2>
Installation</h3>
The easiest way to install Git and to keep up-to-date is to use a package manager.
On Windows you can use Chocolatey</a>:
`# Install Git $ choco install git # Update Git $ choco upgrade git</code></pre>`
On macOS you can use Homebrew</a>:
`# Install Git $ brew install git # Update Git $ brew upgrade git</code></pre> Verify if the installation was successful:`
`$ git --version git version 2.23.0</code></pre>`
Configuration</h3>
Configure your name and email that will be associated with your Git commits.
`git config --global user.name "John Doe" git config --global user.email "john.doe@example.com"</code></pre> Tip: If you want to use different email addresses depending on the repository, you can use the following configuration. This is useful if you have personal and professional email addresses associated with your GitHub account.`
# Remove your email from the global configuration git config --global --unset user.email # Instruct Git to avoid guessing defaults for user.email and user.name git config --global user.useConfigOnly true # Because you haven't configured your email globally, you will see this error when trying to commit: # fatal: no email was given and auto-detection is disabled # To fix it, set your email in each repository: git config user.email "john.doe@example.com"</code></pre> To avoid problems in your diffs, configure Git to properly handle line endings.
# Configure Git on OS X or Linux to properly handle line endings git config --global core.autocrlf input # Configure Git on Windows to properly handle line endings git config --global core.autocrlf true</code></pre> Because you don't want to type your username and password every time Git communicates with the remote repository, you should configure a credential helper.
`# Configure Git on OS X to use the osxkeychain credential helper git config --global credential.helper osxkeychain # Configure Git on Windows to use the credential manager # For Git for Windows 2.29+, use manager-core (or just manager in newer versions) git config --global credential.helper manager</code></pre>`
You might want to create a global .gitignore to exclude your OS files, for example. You can use gitignore.io</a> to generate your .gitignore file.
`git config --global core.excludesfile ~/.gitignore_global</code></pre>`
If you work behind a proxy you can configure Git to use the proxy globally. If you're having HTTPS issues, check out the documentation</a> .
git config --global http.proxy [protocol://][user[:password]@]proxyhost[:port]</code></pre>Everyday user</h2> Updating projects</h3> git fetch</h4> The git fetch</code> command downloads commits, files, and refs from a remote repository into your local repository. Git isolates fetched content by updating remote-tracking branches, not your local branches or working directory. git pull</h4> The git pull</code> command is used to fetch and download content from a remote repository and immediately update the local repository to match that content. The git pull</code> command is a combination of two other commands, git fetch</code> followed by git merge</code>. You can use git pull --rebase</code> if you want to use git rebase</code> instead of git merge</code>. Note: Since Git 2.27, Git will warn you if you haven't set a default reconciliation strategy. You can configure your preference with: # Use merge (default behavior) git config --global pull.rebase false # Use rebase git config --global pull.rebase true # Only fast-forward (fail if not possible) git config --global pull.ff only</code></pre>git merge</h4> The git merge</code> command will combine multiple sequences of commits into one unified history. Assume the following history exists and the current branch is master</code>: E ─ ─ ─ F ─ ─ ─ G feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D master</code></pre> Then git merge feature</code> will create a new merge commit that combines the histories of both branches. This merge commit (H</code>) has two parents: the current tip of master</code> (D</code>) and the tip of feature</code> (G</code>). Git automatically determines how to combine the changes from both branches. E ─ ─ ─ F ─ ─ ─ G feature ╱ ╲ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D ─ ─ H master</code></pre> A fast-forward merge can occur when there is a linear path from the current branch tip to the target branch. Assume the following history exists and the current branch is master</code>: E ─ ─ ─ F ─ ─ ─ G feature ╱ A ─ ─ ─ B master</code></pre> Then git merge [--ff] feature</code> will only update the branch pointer, without creating a merge commit. feature A ─ ─ ─ B ─ ─ ─ E ─ ─ ─ F ─ ─ ─ G master</code></pre> You can force git to create a merge commit during a fast forward merge for record-keeping purposes. Then git merge --no-ff feature</code> will create a merge commit even when the merge resolves as a fast-forward. E ─ ─ ─ F ─ ─ ─ G feature ╱ ╲ A ─ ─ ─ B ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ H master</code></pre> A squash merge allows you to condense the Git history into 1 commit. Assume the following history exists and the current branch is master</code>: E ─ ─ ─ F ─ ─ ─ G feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D master</code></pre> Then git merge feature --squash</code> will take all the commits from feature</code>, squash them into staged changes, and you need to create a new commit (H</code>). Unlike a regular merge, H</code> has no reference to the feature branch commits—it's a completely new commit containing all the changes. E ─ ─ ─ F ─ ─ ─ G feature (unchanged, no connection to H) A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D ─ ─ ─ H master (H contains E+F+G changes)</code></pre> Tip: When squash merging, it's a good practice to delete the source branch. Since H</code> has no parent relationship to the feature branch, keeping the feature branch around can cause confusion—Git won't recognize it as merged. git rebase</h4> While git rebase</code> solves the same problem as git merge</code>, it works differently. Assume the following history exists and the current branch is feature</code>: E ─ ─ ─ F ─ ─ ─ G feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D master</code></pre> git rebase master</code> will move the entire feature branch to begin on the tip of the master branch. But, instead of using a merge commit, rebasing re-writes the project history by creating a brand new commit for each commit in the original branch. It is a good practice to rebase your feature branch against develop to avoid merge conflicts and to simplify the pull request. E' ─ ─ ─ F' ─ ─ ─ G' feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D master</code></pre> Benefits: you get a much cleaner project history</li> you can follow the tip of feature to the beginning of the project without any fork</li> </ul> Warning: The golden rule of git rebase</code> is to never use it on public branches. So, before you run git rebase</code>, always ask yourself, "Is anyone else looking at this branch?" Advanced user</h2> Cherry pick</h3> git cherry-pick</code> allows you to directly apply the changes introduced by some existing commit. Assume the following history exists and the current branch is feature</code>. F ─ ─ ─ G ─ ─ ─ H feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D ─ ─ ─ E master</code></pre> Let's say you want to apply only commit C but not D. Too many people will just manually apply the changes that were made on top of their branch. The right way to do this is to use cherry-pick</code>. $ git branch --show-current feature $ git log --oneline a1b2c3d Add tests b2c3d4e Implement feature c3d4e5f Init feature # Use the actual SHA of commit C from master $ git cherry-pick <sha-of-C> $ git log --oneline f6g7h8i Important fix # New commit with changes from C a1b2c3d Add tests b2c3d4e Implement feature c3d4e5f Init feature</code></pre> Now our history is (note that C'</code> is a new commit with a different SHA than C</code>): F ─ ─ ─ G ─ ─ ─ H ─ ─ ─ C' feature ╱ A ─ ─ ─ B ─ ─ ─ C ─ ─ ─ D ─ ─ ─ E master</code></pre> Tip: You can pass a list of commits to cherry-pick</code>. # Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with these changes. $ git cherry-pick master~4 master~2</code></pre>Rewriting history</h3> Changing the last commit</h4> The git commit --amend</code> command is a convenient way to modify the most recent commit. It lets you: combine staged changes with the previous commit instead of creating an entirely new commit</li> edit the previous commit message without changing its snapshot</li> </ul> You want to edit the commit message. $ git log --oneline fb2f677 The wrong message ac5db87 Previous commit $ git commit --amend -m "The right message" $ git log --oneline 733e2ff The right message ac5db87 Previous commit</code></pre> You forgot to stage some files $ git log --oneline fb2f677 An important feature # Doesn't contain importantFile.txt ac5db87 Previous commit $ git add importantFile.txt # You don't want to change the commit message. If you want, use -m instead of --no-edit $ git commit --amend --no-edit $ git log --oneline 733e2ff An important feature # Contains importantFile.txt ac5db87 Previous commit</code></pre>Changing older commit</h4> The git commit --fixup</code> command, like git commit --amend</code>, allows you to edit a single commit, but this time it doesn't have to be the last one. It can be any commit! After some time, you realize you made a typo, forgot to include a file, or something similar in an old commit "Feature A is done". $ git log --oneline 733e2ff Feature B is done fb2f677 Feature A is done ac5db87 Previous commit</code></pre> Make your changes, use --fixup</code>, and voilà! $ git commit --fixup fb2f677 $ git log --oneline c5069d5 fixup! Feature A is done 733e2ff Feature B is done fb2f677 Feature A is done ac5db87 Previous commit</code></pre> Now you want to clean your branch: use --autosquash</code> option! $ git rebase -i --autosquash ac5db87 pick fb2f677 Feature A is done fixup c5069d5 fixup! Feature A is done pick 733e2ff Feature B is done $ git log --oneline ff4de2a Feature B is done 5478cee Feature A is done ac5db87 Previous commit</code></pre> Tip: You can add this alias to your .gitconfig to make it even simpler! [alias] # Usage: git fixup {sha1} fixup = !sh -c 'SHA=$(git rev-parse $1) \ && git commit --fixup $SHA \ && git rebase -i --autosquash $SHA~' -</code></pre>Changing older or multiple commits</h4> Interactive rebasing can be used for changing commits in many ways such as editing, deleting and squashing. To start an interactive rebase you need to use the SHA-1 of the commit before the oldest (first) commit you want to modify. You can use ~</code> to reference the parent commit. The git rebase -i</code> command will show you commits from oldest to newest and will apply them in this order when rebasing. $ git log --oneline fe0a967 5 228399c 4 6a59879 3 055610e 2 57b5a07 1 $ git rebase -i 57b5a07~ pick 57b5a07 1 pick 055610e 2 pick 6a59879 3 pick 228399c 4 pick fe0a967 5 # Rebase 9f812ce..fe0a967 onto 228399c (5 commands) # # Commands: # p, pick <commit> = use commit # r, reword <commit> = use commit, but edit the commit message # e, edit <commit> = use commit, but stop for amending # s, squash <commit> = use commit, but meld into previous commit # f, fixup <commit> = like "squash", but discard this commit's log message # x, exec <command> = run command (the rest of the line) using shell # b, break = stop here (continue rebase later with 'git rebase --continue') # d, drop <commit> = remove commit # l, label <label> = label current HEAD with a name # t, reset <label> = reset HEAD to a label # m, merge [-C <commit> | -c <commit>] <label> [# <oneline>] # . create a merge commit using the original merge commit's # . message (or the oneline, if no original merge commit was # . specified). Use -c <commit> to reword the commit message. # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out</code></pre> With pick</code> you can change the order of the commits. For example, we can switch 3 and 4 by reordering the lines in the editor: $ git rebase -i 57b5a07~ # Original order shown in editor: pick 57b5a07 1 pick 055610e 2 pick 6a59879 3 pick 228399c 4 pick fe0a967 5 # Change to (swap lines for 3 and 4): pick 57b5a07 1 pick 055610e 2 pick 228399c 4 pick 6a59879 3 pick fe0a967 5 # After saving and closing the editor: $ git log --oneline bf45260 5 6df345c 3 7e49b2a 4 055610e 2 57b5a07 1</code></pre> With reword</code> you can change a commit message. For example, change "2" to "A new message for 2": $ git rebase -i 57b5a07~ # Change 'pick' to 'reword' (or 'r') for commit 2: pick 57b5a07 1 reword 055610e 2 pick 6a59879 3 pick 228399c 4 pick fe0a967 5 # Git will open your editor to change the message for commit 2 $ git log --oneline bf45260 5 6df345c 3 7e49b2a 4 055610e A new message for 2 57b5a07 1</code></pre> edit</code> will allow you to edit a commit: making changes, adding new things to it, or splitting it into several commits. $ git rebase -i 57b5a07~ pick 57b5a07 1 pick 055610e 2 e 6a59879 3 pick 228399c 4 pick fe0a967 5 # Edit your sources $ git commit --amend $ git rebase --continue</code></pre> squash</code> and fixup</code> both allow you to merge commits. The only difference is that squash</code> will let you change the message. $ git rebase -i 57b5a07~ pick 57b5a07 1 pick 055610e 2 s 6a59879 3 pick 228399c 4 pick fe0a967 5 # Save your new message $ git log --oneline bf45260 5 7e49b2a 4 055610e 2 with 3 merged into it 57b5a07 1</code></pre>$ git rebase -i 57b5a07~ pick 57b5a07 1 pick 055610e 2 f 6a59879 3 pick 228399c 4 pick fe0a967 5 $ git log --oneline bf45260 5 7e49b2a 4 055610e 2 # 3 has merged into 2 57b5a07 1</code></pre> Finally, drop</code> will allow you to delete a commit. $ git rebase -i 57b5a07~ pick 57b5a07 1 pick 055610e 2 d 6a59879 3 pick 228399c 4 pick fe0a967 5 $ git log --oneline bf45260 5 7e49b2a 4 055610e 2 57b5a07 1</code></pre> Good to know: git rebase</code> will change the SHA-1 of your commits, so if you already pushed your branch, you'll need to do a git push -f</code>.</li> During git rebase</code>, Git will replay the commits from bottom to top (in the order they were created).</li> You can, of course, mix multiple commands: reword a commit message, squash several commits, etc.</li> </ul> Understanding the staging area</h3> Saving files</h4> Git keeps track of your source tree in several locations locally: Working copy: the directory tree of files that you see and edit.</li> Index (staging area): a single, large, binary file in <baseOfRepo>/.git/index</code>, which lists all files in the current branch, their SHA-1 checksums, timestamps and the file name — it is not another directory with a copy of files in it.</li> HEAD: a reference (pointer) to the current commit, stored in .git/HEAD</code>. It usually points to a branch name, which in turn points to a commit.</li> Object store: the .git/objects</code> directory containing all versions of every file in the repository as compressed "blob" files, along with commits and trees.</li> </ul> Suppose the following state, where oldFile.txt is already committed and we have a newFile.txt. +----------------+ +----------------+ +----------------+ | Working copy | | Index | | HEAD | | oldFile.txt V1 | | oldFile.txt V1 | | oldFile.txt V1 | | newFile.txt V1 | | | | | +----------------+ +----------------+ +----------------+</code></pre> When using git add -u .</code> only tracked files that have changed are staged. Untracked files (like newFile.txt) remain only in the working directory. +----------------+ +----------------+ +----------------+ | Working copy | git add -u . | Index | | HEAD | | oldFile.txt V2 +------------------->+ oldFile.txt V2 | | oldFile.txt V1 | | newFile.txt V1 | | | | | +----------------+ +----------------+ +----------------+</code></pre> Using git reset</code> will remove oldFile.txt (V2) from the index. +----------------+ +----------------+ +----------------+ | Working copy | git reset . | Index | | HEAD | | oldFile.txt V2 +<-------------------+ oldFile.txt V1 | | oldFile.txt V1 | | newFile.txt V1 | | | | | +----------------+ +----------------+ +----------------+</code></pre> git add .</code> adds all files into the index. +----------------+ +----------------+ +----------------+ | Working copy | git add . | Index | | HEAD | | oldFile.txt V2 +------------------->+ oldFile.txt V2 | | oldFile.txt V1 | | newFile.txt V1 | | newFile.txt V1 | | | +----------------+ +----------------+ +----------------+</code></pre> git commit</code> saves the changes into HEAD. +----------------+ +----------------+ +----------------+ | Working copy | | Index | git commit | HEAD | | oldFile.txt V2 | | oldFile.txt V2 +------------------->+ oldFile.txt V2 | | newFile.txt V1 | | newFile.txt V1 | | newFile.txt V1 | +----------------+ +----------------+ +----------------+</code></pre>Undo changes</h4> There are several tools to undo changes: git reset</code>, git checkout</code>, git revert</code>, and since Git 2.23, git restore</code> and git switch</code>. The following table sums up the common use cases for these commands. Command</th> Scope</th> Use case</th></tr></thead> git reset</td> Commit-level</td> Discard commits in a private branch or throw away uncommitted changes. You can use the following options: - --soft</code>: use this when you made bad commits but the work's good and all you need to do is recommit it differently. - --mixed</code> (default option if you don't specify it): use this when you made bad commits but want to keep all the work you've done so you can fix it up and recommit. ---hard</code>: it will throw away your work by resetting the working copy, the index and the HEAD to the specified commit.</td></tr> git reset</td> File-level</td> Unstage a file. It is commonly used with HEAD to retrieve the last committed version of a file. The options --soft</code>, --mixed</code> and --hard</code> are ignored when a path is specified. The index will always be updated and the working copy never updated.</td></tr> git checkout</td> Commit-level</td> Useful for quickly inspecting an old version of your project but it will put you in a detached HEAD state. This can be dangerous if you start adding new commit because there is no way to get them back after switching to another branch. For this reason, you should always create a new branch before adding commits to a detached HEAD. Note: prefer git switch</code> for switching branches (Git 2.23+).</td></tr> git checkout</td> File-level</td> Discard changes in the working directory. Similar to git reset</code> on a file except that it will update the working directory instead of the index. Note: prefer git restore</code> for restoring files (Git 2.23+).</td></tr> git restore</td> File-level</td> (Git 2.23+) Restore working tree files. Use git restore <file></code> to discard changes in working directory, or git restore --staged <file></code> to unstage. This command replaces git checkout -- <file></code> with clearer semantics.</td></tr> git switch</td> Commit-level</td> (Git 2.23+) Switch branches. Use git switch <branch></code> to switch, or git switch -c <branch></code> to create and switch. This command replaces git checkout <branch></code> with clearer semantics.</td></tr> git revert</td> Commit-level</td> Reverting undoes a commit by creating a new commit. This is a safe way to undo changes. Because it doesn't alter existing commit history, it should be used on public branches; use reset</code> on private branches.</td></tr> </tbody></table> Best practices</h2> Define the editor Git uses</h3> I know that you love vi</code>, but I'm sure you prefer Visual Studio Code to write your commit messages, merge, or compare a diff. # Set the editor Git will always use to edit messages git config --global core.editor "code --wait" # Set the editor for diff and merge-conflict-resolution git config --global merge.tool vscode git config --global mergetool.vscode.cmd "code --wait $MERGED" git config --global diff.tool vscode git config --global difftool.vscode.cmd "code --wait --diff $LOCAL $REMOTE"</code></pre>Git flow</h3> Git flow is a collection of Git extensions to provide high-level repository operations. It will help you normalize your branch names across your team. Note: git-flow is installed locally; everyone has to install and configure it. The original nvie/gitflow is unmaintained; consider using the actively maintained git-flow-avh</a> fork instead. Install Git flow</h4> On Windows</h5> Install git-flow-avh using Chocolatey</a>: choco install git-flow-avh</code></pre> Or via Git for Windows</a> which includes git-flow. On Mac OS X</h5> The easiest way to install Git flow on a Mac is via Homebrew</a>: # Install the maintained AVH edition brew install git-flow-avh</code></pre>Useful Git flow commands</h4> # Initialize a new repository with the basic branch structure git flow init -d # Create a feature ABC from an updated develop branch # It will create a branch feature/ABC from develop (up-to-date) git flow feature start -F ABC # Create a hotfix for the version 1.0.0 # It will create a branch hotfix/1.0.0 from master (up-to-date) git flow hotfix start -F 1.0.0 # Create a feature XYZ for this updated hotfix branch # It will create a branch feature/XYZ from hotfix/1.0.0 (up-to-date) git flow feature start -F XYZ hotfix/1.0.0</code></pre>Commit messages</h3> To have a clean Git history we follow the Conventional commit message guidelines. Commit message format</h4> Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject: <type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer></code></pre> Tip: You can create a template Git message with the following to help you use the template. Create a file .gitmessage.txt</code> in your home folder with the following <type>(<scope>): <subject> <body> <footer> # Commit message rules # - Keep lines shorter than 100 characters. # - Only the header is mandatory. # - Type is mandatory and must be one of the following: # - build: Changes that affect the build system or external dependencies # - ci: Changes to our CI configuration files and scripts # - docs: Documentation only changes # - feat: A new feature # - fix: A bug fix # - perf: A code change that improves performance # - refactor: A code change that neither fixes a bug nor adds a feature # - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) # - test: Adding missing tests or correcting existing tests</code></pre> Then add it to your Git configuration git config --global commit.template ~/.gitmessage.txt</code></pre> The header is mandatory and the scope of the header is optional. Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read in git tools. Revert</h4> If the commit reverts a previous commit, it should begin with revert:</code>, followed by the header of the reverted commit. In the body, it should say: This revert commit <hash>.</code>, where the hash is the SHA of the commit being reverted. A commit with this format is automatically created by the git-revert</code></a> command. Type</h4> Must be one of the following. build: Changes that affect the build system or external dependencies</li> ci: Changes to our CI configuration files and scripts</li> docs: Documentation only changes</li> feat: A new feature</li> fix: A bug fix</li> perf: A code change that improves performance</li> refactor: A code change that neither fixes a bug nor adds a feature</li> style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)</li> test: Adding missing tests or correcting existing tests</li> </ul> If you need to use several types, it's probably that your commit is too big and should be split up. Scope</h4> The scope could be anything specifying the place of the commit change. You should define the scopes for your project. You can use *</code> when the change affects more than a single scope. Subject</h4> The subject contains a succinct description of the change: use the imperative, present tense: "change" not "changed" nor "changes"</li> don't capitalize the first letter</li> no dot (.) at the end</li> </ul> Body</h4> Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior. Footer</h4> The footer should contain any information about Breaking Changes and is also the place to reference issues that this commit closes. Breaking Changes should start with the word BREAKING CHANGE:</code> with a space or two newlines. The rest of the commit message is then used for this. References</h2> Pro Git book 2nd Edition</a></li> Git dammit! by Maxime Ghignet</a></li> Dealing with line endings</a></li> Caching your GitHub password in Git</a></li> Getting Git Right</a></li> How to Write a Git Commit Message</a></li> Git Commit Guidelines</a></li> Git flow</a></li> Git flow AVH Edition</a></li> What's the difference between HEAD, working tree and index, in Git?</a></li> In plain English, what does "git reset" do?</a></li> </ul>

Everyday user</h2>

Best practices</h2>

Xavier Balloy

Git: from beginner to advanced user

Xavier Balloy

Git: from beginner to advanced user

Everyday user</h2>

Best practices</h2>