Git and GitHub: saving your work

Every program you have written in this course lives in a folder that changes as you work. Edit a file today and yesterday's version is gone, unless you copied it somewhere by hand. Git keeps those versions for you. It saves your project as a series of snapshots you can go back to, lets you try an idea on a branch while the working version stays safe, and lets a team share one project through a site such as GitHub.

What Git keeps for you#

Without a tool, people keep old versions by copying files: Main.java, Main-old.java, Main-final.java, Main-final-2.java. A week later nobody remembers which copy works, or what changed between them.

Git replaces the pile of copies with a history. It is a version control system: a program that records the state of a folder of files whenever you ask it to. Each record holds every file at that moment, who made the record and when, and a short note saying what changed. Later you can compare any two records, bring back an old version of a file, or find the change that broke something.

A photo album is a good way to picture how Git does this.

• A commit is one photo: a snapshot of the whole project at one moment, with a caption that says what changed. Once taken, a commit never changes.
• The repository is the album: every commit you have made, in order. Git keeps it in a hidden folder called .git inside your project.
• The staging area is the spot in front of the camera. Before each photo, you choose which changes step into the picture, with git add. Changes you leave out stay in your folder and can go into a later photo.

Your first repository#

Before you make a repository, Git needs a few minutes of setup, once per computer.

Setting up Git once#

Open a terminal and ask Git for its version, to check that it is installed:

Version 2.28 or newer has every command this page uses, and the transcripts come from 2.49. If the terminal cannot find git, install it. On Windows, download Git for Windows from git-scm.com. It includes Git Bash, a terminal that understands every command on this page. On macOS, the first time you run git --versionthe system offers to install Apple's command line developer tools, which include Git. On Linux, use your package manager, for example sudo apt install git on Ubuntu.

Next, tell Git who you are. Every commit records a name and an email address, so set them once for your whole computer. The third line makes main the name of the first branch in every new repository, the same name GitHub gives new repositories:

Use your own name and email. These commands print nothing when they work. --globalmeans “for every repository on this computer”, and Git saves the settings in a file called .gitconfig in your home folder. Run git config --list to see them.

Turning a folder into a repository#

Here is a small project to put under Git: a library that holds books and prints them. Book is a record, Library keeps a list of books, and Main fills it. On your computer, each class is its own file: Book.java, Library.java and Main.java. So that you can run it on this page, the three are joined into one here.

Open a terminal in the folder that holds the three files. git init turns the folder into a repository:

ls -a lists hidden files too, the ones whose names start with a dot. The only change is the new .gitfolder. That folder is the repository: every commit you make is stored inside it, while your own files stay where they were. Make one repository per project, in the project's top folder.

Asking Git what is going on: git status

git status is the command you will type most often. Run it whenever you are unsure what Git thinks.

It says you are on the branch main (branches come later in this lesson), that there are no commits yet, and that the three files are untracked: they sit in the folder, but Git is not keeping a history of them. The lines in parentheses are Git's hints about what you can do next, and they are worth reading every time.

Staging and committing

git add puts files into the staging area, exactly as they are at that moment:

The files have moved under “Changes to be committed”. Now take the snapshot. -m gives the commit its message:

Read the first line from the left. The commit went onto main, it is the first commit of the repository (the root commit, the one with no parent), and its id starts with 6d404fe. The next line counts the change, three new files holding 28 lines in all, and the create mode lines list the files that are new in this commit.

Key idea

A commit is a snapshot of the whole project plus a message. You build the next snapshot in the staging area with git add, then save it for good with git commit.

Reading the history: git log

git loglists commits, newest first, with each commit's full id, its author, its date and its message. git log --oneline gives one line per commit with the id shortened, here to its first seven characters, which is enough to name a commit in any command. (HEAD -> main) marks where you are; it will make sense once you meet branches.

The everyday loop: change, check, stage, commit#

Now the project changes. Add a third book to Main.java, on the line after Emma: library.add(new Book("Persuasion", "Jane Austen"));. Save the file and ask Git what it sees:

Main.java is modified: it differs from the version in the last commit. To see how, ask for the difference with git diff:

The a/ file is the old version and the b/ file the new one. The line starting with @@ says where the change is: around line 3, inside public class Main. Lines that start with + were added, lines that start with - were removed, and the rest are unchanged lines shown for context. Here one line was added.

Stage the change and look again:

After git add, plain git diff prints nothing, because it compares your files with the staging area and the two now match. git diff --staged compares the staging area with the last commit, so it shows what the next commit will contain.

Commit the change and check the log:

The history now holds two commits, newest at the top. That is the loop you will repeat all day: edit, git status, git diff, git add, git commit.

Habits that make good commits

• Give each commit one idea. Adding a book and fixing an unrelated typo are two commits. Small commits are easy to read, to review and to undo.
• Write the message as a short instruction, the way Git writes its own: Add a third book, Fix the total for an empty cart. Keep it under about 50 characters. If more needs saying, leave a blank line after it and explain why in a few sentences.
• Commit work that compiles and passes its tests. Run the tests you learned to write in testing with JUnit before each commit, so every point in the history is a version that works.
• Read git status before you commit. It takes a second and catches files you did not mean to include.

Keeping files out: .gitignore#

Compile the project, run it, and look at git status:

javac wrote a .class file for every class, and Git offers to track them. Keep them out of the repository. They are made from the .java files, so anyone can rebuild them, and every change to the code would change them too, filling each commit with differences nobody wrote. Commit what people write, and leave out what tools produce from it.

A file named .gitignorein the project's top folder tells Git which files to leave alone, one pattern per line. This one suits most Java projects:

• Lines that start with # are comments.
• *.class matches every file whose name ends in .class, in any folder. The * stands for any run of characters.
• target/ is the folder where Maven puts compiled classes and packaged programs, and build/is Gradle's. The slash at the end means “folders only”. You meet both tools in Maven and Gradle, next.
• .idea/ is where IntelliJ IDEA keeps its settings for the project. Those describe one person's editor, and they differ from person to person.

Save the file and check again:

The .class files are still in your folder, but Git no longer mentions them. The .gitignore itself is committed, so everyone who works on the project shares the same rules.

Branches: a safe place to try ideas#

Suppose you want to add a search by author. It might take a few tries, and meanwhile you want main to stay a version that works. Branches are made for this.

A branch is a movable label that points at one commit. So far there is one, main, pointing at your latest commit. HEADis Git's name for where you are: it points at the branch you are on. When you commit, the branch that HEAD points at moves forward to the new commit. That is what (HEAD -> main) in the log means: HEAD is on main, and main is on this commit.

git branch lists the branches and stars the one you are on. git switch -c add-search creates a branch called add-search on the commit you are on, and switches to it. No files were copied: the new branch is a second label on the same commit.

Now write the search on this branch. Add a method to Library, then add two lines to Main after library.printAll();: one that prints By Jane Austen: and one that calls library.printByAuthor("Jane Austen");.

Then stage and commit, as usual:

Look at the log. HEAD -> add-search sits on the new commit, and main is still one commit behind. Only the branch you are on moved.

Switching branches changes your files

Compile and run the program on this branch, then switch back to main and do the same:

When you switch, Git rewrites the files in your folder to match the commit that branch points at. On main, printByAuthor does not exist yet: open Library.java in your editor and the method is gone. Switch back to add-search and it returns. Nothing is lost; each branch keeps its own version.

Try it in the lab below. It starts from the project's first three commits, with HEAD on main. Make a branch, commit on it, switch back, and watch which label moves each time. The lab draws the history the way git log --oneline --graph --all does, newest at the top. Then try these: commit twice on a branch, switch to main and merge it; commit on both branches before merging; merge the same branch a second time. The next section explains what you see.

Key idea

A branch is a label on a commit, and HEAD marks the branch you are on. Committing moves only that branch. Switching moves only HEAD, and changes your files to match.

The same idea in Java

If a branch is only a label, you can model one in Java: a map from branch names to commits, where each commit remembers its parent. The record below does that, and the loop at the end walks from the commit main points at back through the parents, the way git log does. Decide what it prints before you run it.

It prints the two older commits, newest first. git switch -c put a second name on the same commit, and committing on add-search moved only that name. main still points where it did, and following parents from there never reaches 874c10a. Each commit points back at its parent, the way each node in a linked list points at the next one.

Merging a branch back#

The search works, so it belongs on main. To merge, switch to the branch that should receive the work (you are already on main), then name the branch to bring in. --all makes git log include the commits of every branch:

Updating e2d4128..874c10a and Fast-forward describe the easy case. main had no commits of its own since add-search started, so Git moved the main label forward to 874c10a. No new commit was needed. This is a fast-forward merge. Then git branch -d deletes the add-search label. Its commit is not deleted: it is part of main now. Git refuses to delete a branch whose commits have not been merged, so -d is safe to use.

When both branches moved: a merge commit

Often mainmoves on while you work on a branch: you fix something there, or a teammate's work arrives. Now neither label can slide forward. Git compares the two branch tips with the commit where they split, combines the changes from both sides, and records the result as a merge commit, a commit with two parents. When the branches changed different files, or parts of a file with unchanged lines between them, this happens by itself, and Git prints Merge made by the 'ort' strategy.(ort is the name of Git's standard way of merging). The lab above does the same when both branches have new commits.

In a terminal, Git first opens your editor with a message such as Merge branch 'add-search' already written. Save and close it to accept the message (in Vim: Esc, then :wq and Enter), or add --no-edit to the merge command to skip the editor.

Fast-forward or not? Write Git's check in Java

Git fast-forwards when the commit your branch points at can be reached from the other branch's commit by following parents. In other words, your branch's commit is an ancestor of theirs. Write that check for the commit model from the Predict above.

1public class Main {
2    public static void main(String[] args) {
3        Commit first = new Commit("6d404fe", "Add a small library app", null);
4        Commit second = new Commit("74e31d6", "Add a third book", first);
5        Commit search = new Commit("874c10a", "Add a search by author", second);
6 
7        Commit mainTip = second;
8        Commit searchTip = search;
9        System.out.println("Fast-forward? " + isAncestor(mainTip, searchTip));
10 
11        Commit rename = new Commit("fed5dfe", "Rename the title", second);
12        mainTip = rename;
13        System.out.println("Fast-forward now? " + isAncestor(mainTip, searchTip));
14    }
15 
16    // true when older is newer itself, or can be reached from newer through parents
17    static boolean isAncestor(Commit older, Commit newer) {
18        return false; // TODO: walk back from newer through parent()
19    }
20}
21 
22record Commit(String id, String message, Commit parent) {
23}

After rename, main points at a commit that the search branch never saw, so Git cannot slide mainforward and would make a merge commit instead. A merge commit has more than one parent, so Git's own check follows all of a commit's parents.

Merge conflicts#

Git combines changes to separate parts of a file without help. When both branches changed the same lines, or lines right next to each other, Git cannot know which version you want, so it stops and asks you. That is a merge conflict. Conflicts are a normal part of working with branches, and fixing one takes a minute once you know where to look.

Here is one, made on purpose. On a branch called friendly-title, the heading line in Main.java changes from My library to Welcome to the library. Meanwhile, on main, the same line changes to Library catalogue:

--graph draws the history: each * is a commit, and the lines show which commit came from which. Both new commits grew from 874c10a, one on each branch. Now merge:

Git merged what it could and stopped at Main.java, which status lists as both modified. Open it in your editor, and you find both versions of the line between markers:

Between <<<<<<< HEAD and ======= is the version on the branch you are on (HEAD, which is main). Between ======= and >>>>>>> friendly-title is the version from the branch you are merging in. To resolve the conflict, edit that part into the code you want, whether that is one side, the other, or something new, and delete the three marker lines. Here the two titles are combined:

1. 1Edit every conflicted file until it holds the code you want and no marker lines are left.
2. 2Compile, run and test, so you know the combined code works.
3. 3Stage each fixed file with git add. That tells Git the conflict is resolved.
4. 4Commit, which records the merge commit.

--no-edit keeps the message Git prepared, Merge branch 'friendly-title'. In the graph, the merge commit 85d5402 has two parents: fed5dfe from main and f5009d2 from friendly-title. The program now greets you with the combined title:

Remotes: sharing your work#

So far the history lives only in your .git folder. A remote is another copy of the repository, usually on a server, that you send commits to and fetch commits from. It is how a team shares one project, and it doubles as a backup of your own. GitHub is the best-known home for remotes; GitLab and Bitbucket are similar, and some companies run their own servers.

On GitHub you create an empty repository on the website, and it shows you the repository's address, such as https://github.com/you/library.git. So that you can follow along without an account, the transcripts below use a folder on the same computer as the remote. Git accepts a folder path as a remote's address just as it accepts a web address, so every command is the one you would type for GitHub, with the address swapped.

A server keeps a bare repository: the history only, with no working files, because nobody edits files on the server. git init --bare makes one. Then connect your project to it and send your commits:

git remote add origin ../server/library.git records the address under the name origin, the usual name for a project's main remote. With GitHub it would be git remote add origin https://github.com/you/library.git. git push -u origin main sends main and every commit it needs. The lines that count objects are progress reports. What matters is at the end: * [new branch] main -> main means the remote now has a branch main, and -u connected your main to it. From now on, plain git push and git pull know where to go, and git status compares your branch with origin/main, Git's record of where main is on the remote.

Cloning: a copy for a teammate

A teammate, Grace, gets her own copy with git clone. It downloads the whole repository, history and all, into a new folder, and sets origin to point back where it came from. From GitHub she would type git clone https://github.com/you/library.git. Here her copy lives in another folder:

Her main and origin/main sit on the same commit, because she has only just cloned. origin/HEADmarks the remote's default branch.

Push and pull

Grace adds The Hobbit to Main.java, commits, and pushes:

85d5402..8116e92 main -> main means the remote's main moved from the old commit to her new one. Back in your folder:

Notice that git statussaid your branch was up to date before the pull. It compares your branch with what Git last heard from the remote, and Git does not contact the remote until you ask, so it could not know about Grace's push yet. git pull then fetched her commit (the From line) and merged it into your main, which here was a fast-forward.

Key idea

Commits travel between repositories only when you ask: git push sends yours, and git pullbrings in everyone else's. Pull before you start work, and push when a piece is done.

When the remote has moved on

Sooner or later, someone pushes while you are working. Grace pushes another book. From here on, the progress lines are cut from the transcripts and marked ...:

Meanwhile you commit a comment in Book.java and try to push it:

The push is rejected because the remote has a commit you do not have, Grace's Add Beloved, and accepting your push would throw it away. The hint says what to do: pull first. This time both sides have new commits, so the pull must merge them, and Git first wants to know how you like that done: