Install and configure Git on your machine

Why do we need Git

Git is an extremely important tool! We use it to do what is known as "version control" -- the act of explicitly curating and keeping track of changes that are made to files in a repository of text files. Using Git, you can even restore files to a previous state. It's like having an extremely powerful undo button at the command line.

Knowing Git also gets you access to the world of open source tooling available on hosted version control storage providers, like GitHub, GitLab, Bitbucket,and more.

How to install Git

macOSLinux

On macOS, you can type git at the Terminal, and a pop-up will show up that prompts you to install XCode and the developer tools for macOS. Accept it, and go about the rest of your day.

Sometimes, the built-in versions of git might be a bit outdated. If you want to install one of the latest versions of git, then you can use Homebrew to install Git:

brew install git

Linux systems usually come with git pre-installed. If you need to install it manually:

sudo apt-get install git

If the above doesn't work for your system, see Git for Linux.

How to configure Git with basic information

You might want to configure git with some basic information.

For example, you might need to configure Git with your username and email address, so that your commits can be attributed to your user accounts on GitHub, GitLab, or Bitbucket. To do this:

git config --global user.name "My name in quotes"
git config --global user.email "myemail@address.com"

This sets your configuration to be "global". However, you can also have "local" (i.e. per-repository) configurations, by changing the --global flag to --local:

# inside a repository, say, your company's project
git config --local user.name "My name in quotes"
git config --local user.email "myemail@company.com"

Doing so is important because you want to ensure that your Git commits are tied to the appropriate email address. Setting the "global" one gives you the convenience of setting a sane default, which you can modify by setting "local", per-repository configuration.

How to configure Git with fancy features

If you installed the cool tools from the system software chapter, then you'll be thrilled to know that you can configure Git to use diff-so-fancy to render diffs!

Follow the instructions in the diff-so-fancy repository. As of 10 December 2020, my favored set of configurations are:

git config --global core.pager "diff-so-fancy | less --tabs=4 -RFX"

git config --global color.ui true

git config --global color.diff-highlight.oldNormal    "red bold"
git config --global color.diff-highlight.oldHighlight "red bold 52"
git config --global color.diff-highlight.newNormal    "green bold"
git config --global color.diff-highlight.newHighlight "green bold 22"

git config --global color.diff.meta       "11"
git config --global color.diff.frag       "magenta bold"
git config --global color.diff.commit     "yellow bold"
git config --global color.diff.old        "red bold"
git config --global color.diff.new        "green bold"
git config --global color.diff.whitespace "red reverse"

Troubleshooting

Git installation issues

Git not found after installation

If git command isn't found:

Check if Git is installed:
```
which git
git --version
```
If these commands return nothing, Git may not be installed or is not in your PATH.
Check your PATH:
```
echo $PATH | tr ':' '\n'
```
Ensure the directory containing the git binary is listed. If you installed Git with Homebrew, it may be in /usr/local/bin or /opt/homebrew/bin.
On macOS, install Xcode Command Line Tools:
```
xcode-select --install
```
On Linux, install Git using your package manager (no sudo recommendation here; use user-level package managers or ask your system administrator if you lack permissions).

Git configuration issues

Configuration not being applied

If your Git configuration isn't working:

Check current configuration:

git config --list
git config --global --list

Verify configuration file location:
```
git config --global --edit
```

Set configuration manually:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Wrong email showing in commits

If commits show the wrong email:

Check repository-specific config:
```
git config --local --list
```

Set local configuration for this repository:

git config --local user.email "work.email@company.com"

Check which config is being used:
```
git config user.email
```

diff-so-fancy configuration issues

diff-so-fancy not working

If diff-so-fancy isn't working:

Check if it's installed:
```
which diff-so-fancy
```

Install if missing:

brew install diff-so-fancy  # macOS
apt install diff-so-fancy   # Ubuntu/Debian (user-level if possible)

Verify Git configuration:
```
git config --global core.pager
```

Reconfigure diff-so-fancy:

git config --global core.pager "diff-so-fancy | less --tabs=4 -RFX"

Common error messages and solutions

"fatal: not a git repository"

# Make sure you are in the directory of your project repository
cd /path/to/your/project

# Initialize a new repository
git init

# Or clone an existing repository
git clone <repository-url>

"fatal: unable to auto-detect email name"

# Set your Git identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

"Permission denied (publickey)"

# Generate SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Add to SSH agent
ssh-add ~/.ssh/id_ed25519

# Add to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub

Productivity Tip: Shell Aliases

For a huge productivity boost, check out the shell aliases guide for useful Git and shell command shortcuts you can add to your environment.

Quick Reference

Essential Git Commands

# Check Git status
git status

# Add files to staging
git add filename
git add .

# Commit changes
git commit -m "Your commit message"

# Push to remote
git push origin main

# Pull from remote
git pull origin main

# Check Git configuration
git config --list

Configuration Commands

# Set global identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set local identity (for specific repository)
git config --local user.email "work.email@company.com"

# Configure diff-so-fancy
git config --global core.pager "diff-so-fancy | less --tabs=4 -RFX"
git config --global color.ui true

Verification Commands

# Check Git installation
git --version

# Check configuration
git config user.name
git config user.email

# Test SSH connection
ssh -T git@github.com