Git Cookbook

The following sections give brief “recipes” for performing common tasks using Git on the command line. This does not try to explain how each command works in detail; for that level of understanding, check the tutorials and references in How to Start Using Git. The commands below all assume they are run on a Unix command line.

Initial Setup¶

Before you run any other Git commands, you should first tell it who you are. It needs this information to assign an “author” to new commits. Run the following two commands:

git config --global user.name "Your Name"

git config --global user.email "emailaddress@example.com"

Starting a Repository¶

Clone a repository off of the remote server¶

Most of the time, you’ll be “cloning” (copying to your local machine) a repository (reponame) that is already set up on the remote server (remote).

In the directory where you want to create a new folder storing your project, run:

git clone git@remote:reponame

For a repository hosted on Github, you can find the correct URL for your repository under the green “Code” button in your repository’s page. Select the “SSH” URL. The result will then be something like:

git clone git@github.com:USERNAME/REPONAME.git

The clone command will create a folder in your current directory named reponame containing the contents of that repository. You should be all set to start adding commits, pushing changes to the remote, and pulling updates from it.

** Alternative: ** Create a new repository locally¶

If you are starting a local repository from scratch, and you do not have a remote to clone from, you can create a new repository locally. This is not as common as cloning an existing repository.

# The commands below should only be run in your project directory,
# so change to that directory first.
cd /path/to/your/project/

# Initialize a new (empty) git repository in the current directory
git init

# Stage whatever initial files you want (possibly just a README)
git add thisfile.txt thatDir/ thisOtherThing.cpp

# Sanity check -- run this often to check things
git status

# Creates a new commit with the staged files selected above
git commit -m "Initial commit of [whatever this is]"

# Ensure the main branch is named 'main'
git branch -m main

Then, whenever the repository is created on a remote server, run the following within your local repository to copy your local state to the remote:

git remote add origin git@remote:reponame
# e.g., on Github, the last part will be git@github.com:USERNAME/REPONAME.git

git push --all -u origin main

The name “origin” is the default remote name. You can use a different name if you like, but for repositories with a single remote, “origin” is a standard choice.

Basic, regular, common-case usage cycle¶

Once you have a local repository set up and connected to a remote, the typical cycle of using it looks like the following:

1. Edit file(s)
2. Check the status of changes: git status (or git status -s for a simpler version)
3. Check exactly what you’ve changed within the files: git diff (or git diff --stat for a simpler version)
4. Add any changes you want to commit to the “staging area”: git add FILE1, git add *.py, git add docs/, etc.
   • This prepares a commit (“staging” it), but it does not finalize the commit.
   • You can add or remove things from the staging area multiple times before you finalize the commit. (To “unstage” a file, removing it from the staging area: git restore --staged FILE)
5. Double-check your staged changes with git status. It will call them “Changes to be committed.”
6. Commit the staged changes to your local repository: git commit -m "message"
   AND ALWAYS PROVIDE A DESCRIPTIVE MESSAGE.
   • Try to make each commit a single independent change and give it a clear commit message describing that one change.
   • If you want to commit every single tracked file that has changed since the last commit, you can skip the git add step and use the -a flag with git commit: git commit -a -m "message" But be careful with this, as you might end up committing changes you hadn’t intended to. If you explicitly use git add to stage individual files, you’ll have more control over what you’re doing.
7. git commit only creates the commit locally — it’s not on the server yet! Collaborators will not see your new commits until you push them to the server. If you want to push (copy) your local repository out to the remote server: git push

Repeat the process for each new set of additions or edits!

Getting the latest changes from the remote server¶

git pull

This will fetch the latest commits from the remote server and merge any changes on the remote into your current branch in your local working directory. Don’t run this if you have uncommitted changes in your working directory. (See man git pull for Git’s own warning).

Sometimes, though rarely, you will want to just grab the latest commits into your local copy of the repository without merging them into the working directory. For that, you can use git fetch.

Tags¶

A “tag” is just a name given to a particular commit. So, essentially, it is giving a name to a particular state of your code at some point in time. Tags are useful for marking version numbers inside your repository, if you release code publicly with version numbers.

To create a tag of the current commit:

git tag TagName -m "Message describing this tag."

Tags must be pushed to the remote repository with a specific command:

git push --tags

Branching¶

Branches are good, and with Git, they’re easy to make and manage. Have you read Chapter 3 of the Pro Git book yet? Branches are really just pointers to commits; being able to visualize what that means and how it affects new commits will help you use them.

To create a new branch starting from the current commit:

git branch mynewbranchname

You can list your branches at any time with:

git branch

Or to see all branches, including remote branches, with info on the most recent commit in each:

git branch -va

You’ll see that your new branch exists, but it’s not yet selected. You can switch to a branch with:

git switch branchname

Switching back and forth between different branches is as easy as that. The switch command will alter the files in your working directory to match the branch (its commit) that you are switching to.

When you’re done with a branch, you can delete it. This should usually only be done after that branch is merged back into another, because otherwise you’re left with one or more commits that are “lost” without a name. To delete a branch:

git branch -d branchname

Remote Branches¶

If you create branches to share with others or if you use branches others have made, then it would be good to read or re-read Section 3.5 of the Pro Git book. I’ll lay out the basics here.

First, if you have created a new branch locally and you want to push it to the remote (e.g., Github), you need to tell Git where to send it and what to name it. If you try to run git push on a branch that doesn’t yet exit on the remote, you will see a note (where <branchname> will be replaced with whatever the branch is actually named):

fatal: The current branch <branchname> has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin <branchname>

To push your new branch to the remote repository and register that remote as the place to push this branch in the future, you can run exactly the command it shows you:

git push --set-upstream origin <branchname>

You can switch to a remote branch that someone else has created (and thus that does not yet exist locally for you) by pulling the repository and using the switch command. For example, if someone else made a branch named newbranch and pushed that to the remote, you could run:

git pull
git switch newbranch

The following is not common, but if you need to delete a branch off of the remote (assuming the remote is called “origin”):

git push origin :branchname

And if another repository still has that remote branch after you’ve deleted it on “origin,” you can run this to clear out the stale references:

git remote prune origin

Merging¶

Merge a branch otherBranch into the current branch with:

git merge otherBranch

(If you end up in an interface asking you to type a message for the new merge commit, you just need to exit that program to accept the default message. The default editor in many cases is a program called Vim, which you can exit by typing :q and pressing enter.)

If there are no conflicts, you’re good. Run git log to see the new commit created for the merge. If you don’t want the old branch name around any more, you can remove it with:

git branch -d otherBranch

(After its commits have been merged, deleting the other branch only removes the branch’s name from your repository. The commits will be unaffected.)

If there are conflicts, the high-level approach to resolving them is:

• See the status of the merge commit under consideration: git status
• Open any file with merge conflicts directly in your text editor of choice. You will find markings showing changes that could not be merged automatically… Look these over carefully, edit the file to contain the version you want, and then run git commit -m '...' with a message describing the merge to seal the deal.
• Alternatively, you can try git mergetool to merge the changes with a tool like gvimdiff (but be warned, it is not intuitive to use if you’ve never used vim).

This guide goes into more detail on how to resolve merge conflicts using the command line. However, you do not want to run git add . in their step 7. That is likely to bring more files and changes into the commit than you want. Instead, specify individual files using git add until the “to be committed” part of git status contains everything you want to commit in the merge.