In the previous lesson we learned the configuration mechanism: git config, its levels and its precedence. Now it is time to apply it. This lesson walks through the specific values worth setting on a machine before you start working, and it does so alongside Ana as she gets her laptop ready to start task-manager.

Some of these settings are mandatory: without them Git will refuse to commit, or will commit with wrong data that can afterwards only be fixed by rewriting the history. Others are strongly advisable because they head off unpleasant surprises: getting trapped in an unfamiliar editor, having a colleague on another operating system see the whole file as modified, or having Git perform unexpected merges when integrating changes.

By the end, Ana's machine will be ready and we will close the module by handing over to module 2, where she finally creates the repository.

1. Identity: user.name and user.email
2. The default branch: init.defaultBranch
3. The editor: core.editor
4. Line endings: core.autocrlf and core.eol
5. Behaviour when integrating: pull.rebase
6. Behaviour when pushing: push.default
7. Credentials: credential.helper
8. Colour and language of the output
9. Summary table of recommended settings
10. Final check of Ana's machine

This is the only genuinely mandatory setting. Every commit records who made it, and Git refuses to create one if it does not know who you are.

Breaking it down:

• --global writes to ~/.gitconfig, so it applies to every one of Ana's repositories. That is the right place for your identity.
• user.name is your name as it will appear in the history. Use your real, full name: it is what your colleagues will see for years on every line of the history. Nothing stops you using a nickname, but it makes attribution harder to follow.
• user.email is the address attached to the commit. It is the field hosting platforms use to link a commit to a user account: if the address does not match one registered on GitHub or GitLab, the commit will show up with no profile picture and no link.

When you try to commit, Git shows an explicit error:

In some older setups Git did not fail but guessed an identity from the user name and the machine name, producing authors like [email protected]. That behaviour is discouraged and off by default in modern versions, precisely because it produced histories with useless attribution.

The author is part of the commit object, and we saw in The Git Data Model that the hash is computed over that content. Changing the author of an existing commit means creating a new commit and rewriting the whole history that follows it. If that history is already shared, the problem multiplies.

In practical terms: set your identity before your first commit, not afterwards.

If you publish on GitHub and would rather not expose your real address, the platform offers a forwarding address of the form [email protected]. You configure it the same way:

Commits still get linked to your account, but your real address stays out of the public history. Remember that the history is permanent: an address that has been committed and published cannot be withdrawn without a rewrite.

As we saw in Configuring Git, local configuration solves this, or better still includeIf. Ana already has her ~/personal/ folder set up for exactly that.

When a repository is created, Git automatically creates a first branch. Historically it was called master; since 2020 the industry's de facto standard is main, adopted by GitHub, GitLab and most new projects.

Without this setting, Git carries on using master and prints a long notice every time a repository is created, reminding you that the default name is subject to change. Setting it removes the notice and, more importantly, avoids the inconsistency of having repositories with master locally and main on the server.

Two important qualifications:

• It only affects new repositories. Existing ones keep whatever name they had.
• It renames nothing. If you work on older projects using master, they will carry on being called that, and there is nothing wrong with it.

Git opens a text editor in several situations: writing a long commit message, working through an interactive rebase, editing the configuration with --edit. If it is not configured, Git uses the value of the GIT_EDITOR, VISUAL or EDITOR environment variables, and failing all of those, Vim on most Unix systems.

That last case is a classic: a beginner runs a command, an incomprehensible blue screen appears, and they cannot get out. (In case it happens to you: press Esc, then :q! and Enter to discard, or :wq to save.)

Configure the editor you already know how to use:

The critical part with graphical editors is the wait option:

• --wait in VS Code, -w in Sublime.
• Without it, the editor opens and hands control straight back to Git, so Git believes you have finished and receives an empty file. The result is a blank commit message and an aborted operation.

Ana codes in VS Code, so:

A requirement on macOS for VS Code. The code command has to be available on the PATH. You enable it from VS Code itself through the command palette (Cmd+Shift+P) → Shell Command: Install 'code' command in PATH.

This is the setting that causes the most trouble in teams with mixed operating systems, and task-manager is exactly that case: Ana on Linux, Bruno on macOS and Carla on Windows.

Operating systems mark the end of a line differently:

To Git, which compares content byte by byte, a file with LF and the same file with CRLF are different contents, with different hashes. Left untreated, this happens: Carla clones the project on Windows, her editor converts the line endings on save, and suddenly Git tells her all four files are modified from top to bottom, even though she has not changed a single word. Her next commit will change 100 % of the lines and make any code review unreadable.

The universal convention is to always store LF inside the repository and convert on the fly on the systems that need it.

What each value does exactly:

With this configuration the repository always holds LF, Carla sees CRLF on her disk the way Windows expects, and Ana and Bruno see LF. Nobody sees phantom changes.

This is a complementary setting defining which line ending gets written to disk for files explicitly marked as text:

Possible values: lf, crlf or native (the system's own, which is the default). It only comes into play when core.autocrlf is false and file attributes are defined.

core.autocrlf is a personal setting: it depends on every team member having got it right on their own machine. The robust answer is a .gitattributes file versioned inside the project, which imposes the rule on everyone regardless of their configuration:

This file gets full treatment in module 8, in the lesson File Attributes with .gitattributes. Treat it here as the goal to work towards; core.autocrlf is the individual safety net in the meantime.

When you download changes from the remote and your local branch has also moved on, Git has to integrate the two lines. There are three ways of doing it, and since version 2.27 Git refuses to choose for you: it prints a notice and insists you configure which one you prefer.

The recommendation to start with: pull.ff only. It is the most conservative option: when the two lines of development do not clash, it integrates without noise; when they do, it stops and tells you to decide. That way you learn to recognise the situation instead of having Git make a silent decision you do not yet understand.

Plenty of experienced teams prefer pull.rebase true to keep the history linear. That is a legitimate choice, but it means understanding rebase and its risks, which module 5 covers. When you get there you will be able to change the value knowing exactly what you are doing.

A complementary setting, highly advisable if you later turn on automatic rebasing:

It stashes uncommitted changes before the rebase and restores them afterwards, avoiding the "cannot rebase: You have unstaged changes" error. Stashing is covered in module 5.

This determines which branches are pushed when you run git push with no arguments.

simple has been the default since Git 2.0 and it is the recommended value: it pushes the current branch only, and only when its name matches that of the remote branch it tracks. It is the least surprising behaviour.

A very practical companion:

Available since Git 2.37, it makes Git set up a new branch's tracking automatically the first time you push it, instead of failing with fatal: The current branch X has no upstream branch. It saves typing git push --set-upstream origin <branch> every time you create a branch, which in a branch-based workflow happens daily.

Remotes and pushing changes are the content of module 4; here we are only laying the groundwork.

When you work with remote repositories over HTTPS, Git will ask for a username and password — in reality, an access token — on every operation. A credential helper stores them securely so you do not have to repeat them.

A warning about store. It saves credentials unencrypted, in readable text. It turns up in a great many tutorials because it is the simplest, and it is a bad security practice. Module 8 devotes a lesson to security best practices.

The alternative to all of this is to use SSH instead of HTTPS, with cryptographic keys instead of passwords. It is what teams usually prefer, and module 4 covers it in the lesson on authenticating with remote repositories.

auto turns colour on when the output goes to a terminal and off when it goes to a file or another program, keeping escape codes out of your dumps. It is usually on by default in modern Git, but setting it explicitly does no harm.

You can tune it per command:

And customise specific colours, with the syntax <foreground> <background> <attribute>:

It is optional and a matter of taste; color.ui auto is enough to work comfortably.

Git translates its messages into the system's language whenever a translation exists. On a machine set to another locale git status comes back translated; in English it reads like this:

There is a practical decision to make here. This course recommends leaving Git's output in English, for three concrete reasons:

1. Almost all the documentation, the manuals and the answers you find when you search for an error message are in English. Searching for the exact text of a translated error rarely returns anything.
2. The translations are partial: you end up with messages mixed across two languages.
3. The examples in this course, and in any technical material, show the output in English.

To force it, if your system runs in another language:

If you would rather keep the rest of your system in its own language and affect Git alone, there is a dedicated variable:

On Windows, Git Bash uses the installer's language; the environment variable works there too if you define it in the shell's startup file.

Ana keeps hers in English so the messages match the documentation.

This is the complete set Ana applies on her laptop, with the reasoning behind each one:

And here is the whole thing together, exactly as Ana runs it on her Linux laptop. You can copy this block, changing the name, the address and the editor:

The resulting ~/.gitconfig file:

Twelve lines of configuration that head off most of the common stumbles of the first few months.

Before calling the machine ready, Ana verifies that everything is in place. These are the checks, with the expected output.

If either of the two returns nothing, it is still unconfigured and Git will not let you commit.

This shows each key along with the file it came from. Now is the moment to catch typos: check that the key names are exactly the ones in the table in section 9.

Your editor should open with the contents of ~/.gitconfig. Close it without saving. If Vim opens instead of your editor, or if the command hands control back instantly without opening anything, review core.editor and check that it includes the wait option (--wait, -w).

With all seven boxes ticked, Ana's laptop is ready.

• Starting to commit without setting your identity. It is the costliest error in the module, because correcting the author on commits already made forces a history rewrite. Set user.name and user.email before creating your first repository.
• Configuring a graphical editor without the wait option. code instead of code --wait makes Git receive an empty message and abort the operation. The symptom is "the editor opens and Git says the message is empty".
• Ignoring line endings until the team goes mixed. When Carla joins the project from Windows without core.autocrlf, her first commit shows up changing 100 % of the lines in every file. Configure it from the start and, as soon as there is a shared project, add a .gitattributes (module 8).
• Using credential.helper store. It keeps passwords in plain text in your home folder. Use your system's native helper or, better still, SSH.
• Writing the configuration into the local level by accident. As we saw in the previous lesson, leaving out --global writes to .git/config. For your identity and your personal preferences, the correct level is always the global one.
• Copying configuration blocks off the internet without understanding them. Exotic settings turn up that change important behaviour and then produce effects that are hard to explain. Add options one at a time, knowing what each one does.
• Tip: review the configuration when you change machine or company. A corporate laptop may come with values at the system level (proxies, credential helpers, templates) that you are not expecting. git config --list --show-origin --show-scope is the first thing worth looking at.
• Tip: put your ~/.gitconfig under version control. It is a small text file that represents a lot of accumulated tuning. Keeping it in a repository of your own lets you reproduce your environment on any new machine in a minute.

Apply the full recommended configuration on your machine, adapting it to your case:

1. Set your identity with your real name and your e-mail address.
2. Set main as the default branch.
3. Configure the editor you know how to use, with the wait option if it is graphical.
4. Configure core.autocrlf with the value that is correct for your operating system.
5. Set pull.ff only, push.default simple and color.ui auto.
6. Run the five checks from section 10 and note the output of each.
7. Display the resulting contents of your ~/.gitconfig and compare it with Ana's.

The task-manager team is a mixed bunch:

• Ana: Ubuntu, VS Code as her editor, address [email protected].
• Bruno: macOS, Vim as his editor, address [email protected]. He also wants HTTPS credentials stored in the system Keychain.
• Carla: Windows 11 with Git Bash, Notepad++ as her editor, address [email protected]. She also works on projects for another company, kept in C:\Users\carla\company\, which must use the address [email protected].

Write the sequence of configuration commands for each of them. Pay particular attention to core.autocrlf on each system and, for Carla, solve the two-address case using what you learned in the lesson Configuring Git.

A newly arrived colleague complains about three separate problems and shows you the result of git config --global --list:

His complaints are:

1. "Git won't let me commit, it says it doesn't know who I am."
2. "When I write a long message, VS Code opens but Git immediately says the message is empty."
3. "When I integrate changes from the remote, my commits change identifier and my colleague says I've messed up the history."

For each complaint: identify the exact cause in that configuration, write the command that fixes it and briefly explain why. Also say whether there is anything in that list that is not a problem even though it looks like one.

Solution to Exercise 1

A worked example for a Linux user called Marta Pons:

Point 4 is the one that varies most: on Windows it has to be true, not input. Point 3 only needs the wait option if the editor is graphical (code --wait, subl -n -w); terminal editors such as nano or vim block by their very nature.

Solution to Exercise 2

Ana — Ubuntu

Bruno — macOS

core.autocrlf is input just as on Linux, because macOS also uses LF. Vim needs no wait option.

Carla — Windows 11

And for the second address, editing ~/.gitconfig (which on Windows lives at C:\Users\carla\.gitconfig) to add at the end:

With the file ~/.gitconfig-othercompany:

Three important details in Carla's solution:

• gitdir/i: is used instead of gitdir: because the Windows filesystem is case-insensitive, and the insensitive variant avoids failures caused by capitalisation differences in the path.
• The path is written with forward slashes (/), not backslashes, even on Windows: Git always uses forward slashes in its configuration files.
• The path ends in /, a requirement for the match to be recursive.

Checking from any repository under C:\Users\carla\company\:

Solution to Exercise 3

Complaint 1 — "it doesn't know who I am"

• Cause: the key is misspelled. It reads user.emial instead of user.email. Since Git does not validate key names, it stored it without complaint and user.email is still undefined.
• Fix:

Complaint 2 — "the message is empty"

• Cause: core.editor=code is missing the --wait option. VS Code opens and hands control straight back to Git, so Git reads the message file before anything has been written and aborts because the message is empty.
• Fix:

Complaint 3 — "I've messed up the history"

• Cause: pull.rebase=true reapplies the local commits on top of the downloaded ones, which creates new commits with a different hash, as we saw in The Git Data Model. If those commits were already shared, the colleague finds himself with diverged histories. It is not an "incorrect" value in itself — plenty of teams use it deliberately — but it is not appropriate for someone starting out who cannot yet tell when it is safe.
• Fix for a beginner:

That way, if divergence appears while integrating, Git stops and warns instead of rewriting anything. When the colleague reaches module 5 he will be able to turn rebasing back on with good judgement.

What is NOT a problem: the line init.defaultbranch=main. Configuration keys are case-insensitive in both the section and the name, so init.defaultbranch and init.defaultBranch are exactly the same key. Git in fact normalises the name to lowercase when listing the configuration, so that line will appear that way even if it was written with the capital. It works perfectly.

Ana's laptop is ready. We have set the two mandatory values — user.name and user.email, which identify the author on every commit and are worth getting right before the first one, because correcting them afterwards forces a history rewrite — and a dozen strongly advisable settings: init.defaultBranch=main to line up with the industry standard, core.editor so you never get trapped in an unfamiliar editor, core.autocrlf so that a team on Linux, macOS and Windows does not generate phantom changes in every file, pull.ff only so Git never integrates unexpectedly, push.default and push.autoSetupRemote so pushing is predictable, a secure credential helper and the output colours.

That closes module 1. Across these six lessons we have covered the full road from knowing nothing to having a prepared environment:

• Why Git exists and what sets it apart from centralised systems, with task-manager as the guiding project.
• How to install it on Linux, macOS and Windows, and why we will use the command line.
• The vocabulary: three areas, three states, references, remotes, merge and rebase.
• The data model: blobs, trees, commits and tags linked by hash, and the immutability that follows from it.
• The configuration mechanism: three levels, precedence and conditional profiles.
• The specific values that leave a machine ready to work.

You know what Git is, you have it installed, you understand how it stores information and it is configured to suit you. All that is left is to use it.

Module 2: Basic Git Operations is where the real work starts. Ana will finally turn her task-manager folder into a repository in Creating a Repository, we will learn to clone an existing one, we will walk the basic workflow connecting the three areas you already know, and we will practise thoroughly how to stage and commit changes, inspect differences and read the history. Everything you have learned here about the three areas, the objects and the references will start to be visible in action.