Skip to content

Git Basics

Now that we have a project and a git repository let's start using it. Here are the basic commands you'll be using this semester.

How this page fits with Git Overview

The Git Overview page covers the concepts—version control, repositories, and how Git differs from GitHub. This page is the hands-on companion: the exact commands you will type, and what you will see when you run them.

The Core Commands

You will use four commands constantly, almost always in this order:

  1. git status — see what has changed in your project.
  2. git add — stage the changes you want to save.
  3. git commit — save a snapshot of the staged changes to your local repository.
  4. git push — send your commits up to GitHub.

Each command is explained in detail below.

$ git status

Use this command to see what git sees as the changes to your project. You should use this more than any other command.

  • Examples:
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
nothing to commit, working directory clean

$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)

    modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

$ git add <filepath>

We have to add files to git after we add them to our project. First use git status to see all new files. Then use the add command.

  • Examples:
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)

    modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    src/java112/labs1/JustADemo.java

no changes added to commit (use "git add" and/or "git commit -a")

git add src/java112/labs1/JustADemo.java

$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)

    new file:   src/java112/labs1/JustADemo.java

Shortcut: git add .

To stage all new and modified files at once, use git add . (the dot means the current directory and everything in it). This is a handy shortcut when you have several changes to add instead of listing each file individually.

$ git commit ...

Notice that it says Changes to be committed:? Any time we change something in our project, we have to commit—the change can be a new file or an edit to an existing file. This is the habit we have to get into. Here's how.

All the pieces of this command are required for it to work correctly. Here's the breakdown.

  • git commit: This is the command and it requires more information.
  • -m: This stands for "message". With the m you have to have set of double quotes with a commit message. The message is for your teammates and needs to say what was done in this commit.
  • "Initial commit of my semester project.": This will be your message. It does not need to be long but it must state generally what was done in your project since the last commit. The first time we commit a project we usually mention something like "Initial commit".
  • Example:
$ git commit -m "Adding a file to demonstrate an add. Modifying a file to demonstrate a change."
[main a28a889] Adding a file to demonstrate an add. Modifying a file to demonstrate a change.
 2 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 src/java112/labs1/JustADemo.java

After a commit you should do a git status to verify everything was committed.

$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

Notice that the status message says Your branch is ahead of 'origin/main' by 1 commit. This means it's time for a push.

What is an atomic commit?

An atomic commit does one logical unit of work. Each commit should have a single, clear purpose so that your Git history reads like a record of your development process, one step at a time.

Atomic commits matter because they make your history easier to understand, make bugs easier to trace, and make it possible to undo one change without affecting unrelated work.

Good commit messages (one change, clear purpose): 

Add countTokens method to FileSummaryAnalyzer
Fix file-not-found exception handling
Add Javadoc to DistinctTokensAnalyzer

Poor commit messages (vague or bundled): 

Finished everything
Final changes
Stuff

Atomic vs. not atomic: 

Add countTokens method                                            ← atomic: one thing
Add countTokens, fix tests, update Javadoc, clean up formatting  ← not atomic: four things

A good rule of thumb: if your commit message needs the word "and," the commit probably does too much.

$ git push

A commit is local to your Codespace, it does not save your repository to GitHub. You need to do that step with a push. The way we have set things up you only need to enter $ git push.

$ git push
Counting objects: 7, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (7/7), 835 bytes | 0 bytes/s, done.
Total 7 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To git@github.com:madcol-advjava-s18/projects-<account>.git
   20eeafd..4076ab2  main -> main

This is good!

Tips

  • Use git status often!
  • Add, commit, and push each time you have a bit of functionality working — often just a few lines of code.
  • You can combine add and commit into a single step with git commit -am:
$ git commit -am "Adding Lexical Density Analyzer"

git commit -am skips brand-new files

git commit -am only stages files that git is already tracking. If you created a brand-new file, you must run git add <filepath> first.

When in doubt, use git status to understand the state of your files.

AI and commit messages

AI tools can help you write commit messages. Try: "I just wrote a method that reads a file line by line and stores each token in an ArrayList. Write me a git commit message."

Evaluate the result. A good commit message is specific enough that you (or a teammate) can understand the change six months from now without looking at the diff. A vague AI message is worse than a short human one.

Using Git in VS Code

VS Code has a built-in Source Control panel that maps directly to the terminal commands above.

Terminal Command VS Code Action
git status Open the Source Control sidebar (Ctrl+Shift+G / Cmd+Shift+G)
git add <file> Click + next to a file under "Changes"
git commit -m "..." Type your message in the text box and click the ✓ checkmark
git push Click the ... menu → Push, or use the sync button in the status bar

Use the terminal for this course

The VS Code GUI is convenient, but this course uses terminal commands in labs and on assessments. Learn the terminal commands first. Use the VS Code panel only to visually confirm what you've already done in the terminal.

The .gitignore File

Your project already includes a .gitignore file that tells git which files to ignore. You should never need to edit it, but you should understand what it does.

Here are the key rules in your .gitignore and why they're there:

Pattern What it ignores Why
*.txt, *.TXT All text files bigFile.txt is too large to store in a repo — ignoring all .txt files keeps it out automatically
*.dat Data files Same reason — large generated data files don't belong in version control
output/*.txt Text files in the output folder Anything your program writes to output/ is generated and should not be committed
build/, dist/ Build output directories These are generated by Ant — never commit compiled output
lib/analyzer.jar, lib/java112Labs.jar Generated jar files These are built by Ant from your source code — commit the source, not the compiled artifact
lib/*.war, lib/*.ear Web archive files Same — generated output
docs/project_api/ Generated Javadoc Javadoc is generated from your source — commit the source comments, not the HTML output
.DS_Store macOS metadata This file is created by macOS Finder and has no meaning to your teammates or your code
*~, *# Editor backup files These are temporary files created by some text editors
TEST* Test output files Test result files are generated and should not be committed
hs_err_pid* JVM crash dumps These are generated when the JVM crashes — not part of your source

.txt files will not be committed

For our projects, we use a file called, bigFile.txt, and is very large. For this reason, all .txt files are excluded from your repository. If you create a small text file you want to commit, for example, a notes file or sample input rename it to use a different extension. A .md file works well for notes and plain text content, and git will track it normally.