Basic command-line git

A typical work session with git requires you to know only a handful of basic git operations and commands. While git does provide many powerful and versatile tools for dealing with files across versions and collaborators, these commands (and the operations they invoke) will carry you through most situations.

This is a guide to interacting with git using command-line invocations. These commands and the operations they perform share the same name; if you are using a GUI git tool (e.g., built into an IDE) then the operations available to you will match the commands you see here.

First-time configuration of global git attributes

Before you use git for the first time, there are a couple of important configuration details you must set to allow git to work properly. This is done using the command git config command, with the option flag --global.

Git initial user configuration

Git attaches your name and email to every commit you make, so you need to configure them before you start working:

$ git config --global user.name "Your name" $ git config --global user.email "Your email address"

Git also allows you to configure the default name of the first branch created in a new repository:

Git default branch name configuration

$ git config --global init.defaultbranch "default_name"

Git default branch names: a brief history

Historically, the default name for the first branch in a repo was master. This was inherited from Bitkeeper (a predecessor to git) which used the term "master repository" to refer to the single, authoritative copy of the code while all other copies were referred to as "slave repositories." (The use of master/slave terminology in technology has, unfortunately, been quite common in the past).

More recently, many organizations using git have opted to change this default to something with less historical baggage. Popular choices include:

main, inspired by languages like C/C++ where the main function is the first to execute
prod (short for "production"), indicating that this branch represents the code which will be shipped to clients
stable, indicating that code on this branch should be well-tested and unlikely to crash

Git stores your configuration settings in a text file named .gitconfig kept in your home directory. Config settings stored here are the defaults for every repo on your computer.

You can also set local configuration settings that apply to a single git repo. These are stored in a .gitconfig within the repo itself. Git reads the global config file first, then the local file, so that the local settings override your global defaults.

Creating and cloning repositories

You must establish a git repository on your computer before you can make changes which are tracked by git. There are two ways to establish a repository: you can create a new repository (e.g., to begin work on a new project); or you can clone an existing repository (e.g., to begin collaborating on an existing repository). Whichever option you use, you'll only have to take this step once.

Establishing a new repository

You establish a new git repository by first choosing or creating a directory to contain the repository. The repository name will be exactly the same as the directory name, so choose your directory name appropriately.

Once you've selected a location for the new repo, set it as your working directory and then create the repo with the init command.

git init - Create an empty git repository

$ git init

This initializes a new subdirectory, .git (which git uses for version tracking). You're now ready to go to work on the files in the repo.

Cloning an existing repository

Alternatively, you can clone an existing repository, creating a new copy of the files and version history it contains. This is common when multiple people collaborate on a project, with each keeping a repository on their local machine.

You begin by selecting a directory to store the cloned repository. Wherever you choose, the cloning operation will create a new subdirectory (with the same name as the repo) and that subdirectory will contain the repository files.

Once you've selected the location to clone, you use the clone command to begin the operation.

git clone - Clone a repository

$ git clone [options] repository

Git keeps track of the repository you clone from and refers to it as a remote repo (in contrast to your local repo). The typical git workflow includes syncing your local repo with the remote to share your work with others (and get others work into your local repo).

One to specify the repository you want to clone is by providing a URL for an Internet computer where the repository is stored. GitHub is the most popular web service for hosting repositories in this fashion.

It's very common for collaborators to keep a copy of their repo on GitHub and for every person to clone from that repo. This lets the collaborators share their work by syncing their local repo with the GitHub repo; that way, no two people have to be available to directly sync between their copies of the repo.

A typical git work session

You usually establish a git repo once, then work on it over multiple days/weeks/months/years... creating and modifying files. A typical work session using git involves the following steps:

Pulling changes others made while you were away
Checking out a version of the code to make changes to
Creating, modifying or removing files to do work
Commiting your changes to save a new version of the project
Pushing your changes to that others can see them

The first and last steps may not be necessary if your project is a personal one and confined to a single repo (on your computer) but they are absolutely critical if multiple copies of the repo exist -- either because you work from different places or because you are collaborating with another person.

Pulling changes others made while you were away

The first step in your workday -- before you settle into do work yourself -- is to sync your local repo with the remote repo where others have shared their work. This ensures that you're working with the most up-to-date versions of all the files in your project. You do this by pulling changes from the remote with the pull command.

git pull - Fetch from and integrate with another repository

$ git pull [remote]

Typically, the default remote to pull from is the one you cloned from initially; git nicknames this remote origin by default.

Checking out a version of code to make changes to

You make changes to your repo by starting from an existing verison of the files and then making changes to them. This means you need to check out the version of the repo you're going to start from before you do any work.

git checkout - Switch branches or restore working tree files

$ git checkout [branch] $ git checkout [filename]

Git lets you organize sequences of changes into branches with memorable names so that you can check out a branch and continue where you left off.

You can also use this command to "reset" a file back to its original state, undoing any changes you made to it since you started working.

Creating, modifying or removing files to do work

This is the point where you're ready to go to work; it's also the point where git takes a backseat to your other programming tools! The files and directories in your repo are just that: regular files and regular directories. This means that you can create new files or directories; open existing files (in any editor you like) and make changes to them; or even rename or delete files you no longer want.

Git does keep track of your changes while you work; at any time, you can ask git to summarize the files you've created, modified, or removed by using the status command.

git status - Show the working tree status

$ git status

This command lists everything that has changed (compared to the commit you checked out). The changes are listed as either staged or unstaged, which becomes important in the next step.

Committing your changes to save a new version of the project

When you've done enough work and you're ready to create a new version of your files, you begin by identifying the files whose changes you want to save and adding them.

git add - Add file contents to the index

$ git add filename

Adding a file moves its changes from unstaged to staged (as reported by git status); this operation is also called staging for this reason. Only staged changes are included in the next step (though unstaged changes are not lost).

Once you've staged your changes, you commit those changes to make them a permanent part of the version history. Git calls individual versions commits as well, meaning you "commit a new commit" at this point.

git commit - Record changes to the repository

$ git commit [-m "msg"]

Git automatically records your name and email as part of the new commit. Git also requires that you provide a message, meant to explain the changes you made and/or the work you did. If you use the -m option, then the (double-quoted) string you provide serves as your commit message. If you leave this option off, then git will automatically open your default text editor for you to type a commit message in (recording the message when you save and quit).

Image source: xkcd: Git by Randall Munroe (image link)

Pushing your changes so that others can see them

The last step in your workday mirrors the first -- you need to share your commits with others by sycing your repo with the remote. This time, you're pushing the commits you made to the remote so that others can retrieve them later.

git push - Update remote refs

$ git push [remote]

It's a good idea to push your changes whenever you stop working for longer than it takes to, say, get a cup of coffee. There's two good reasons for this: first, it shortens the time between when you do work and when your collaborators see that work; and second, it copies your work to a remote machine, creating a backup in case something goes wrong (e.g., you spill your coffee on your laptop).