Terminology

Repository

You can think of a repository (repo) as a version controlled directory for one or more projects. A repo contains all of the projects files, code, documentation, etc., along with the project’s entire revision history. When a single repo contains the code and project files for many projects, it can sometimes be referred to as a monorepo. Repos are typically either public or private. public repos are open to anyone who can access the website. private repos are only open to those who have been explicitly given permissions to the repo.

It is obvious when looking at a project on GitHub what a repo is, but what about on your own computer? What makes a folder a repo? Where are all of the version control components located? The answer is in the hidden .git folder in your project directory. For example, my_project is a repo, with all of the commits, repo addresses, etc., placed in the .git folder. If you were to remove the .git folder, the my_project directory would no longer be a repository, but rather a normal directory.

Repository example

my_project
├── .git
│   ├── HEAD
│   ├── config
│   ├── description
│   ├── hooks
│   │   └── README.sample
│   ├── info
│   │   └── exclude
│   ├── objects
│   │   ├── info
│   │   └── pack
│   └── refs
│       ├── heads
│       └── tags
├── .gitignore
├── Cargo.toml
├── LICENSE
├── README.md
├── docs
├── scripts
├── src
│   └── main.rs
└── tests

13 directories, 10 files

To initialize a new repository from a currently existing project directory, there are a few commands to learn.

cd my_project (1)
git init (2)
git remote add origin git@github.com:exampleuser/my_project.git (3)
git branch -M main (4)
git push -u origin main (5)

1	Navigate to the root of the project directory.
2	Initialize the repository, this is the command that creates the `.git` directory.
3	Essentially links the local repo (on your computer) to the remote repo (on GitHub). When we run commands like `git fetch` or `git pull` `git` now knows where to fetch or pull the data from.
4	By default `git` names the default branch of a repository `master` (repos created on GitHub are named `main` by default). `git branch -M main` is the command to move or rename the default `master` branch to be named `main`.
5	This command sets the upstream branch for the `main` branch. Once the upstream is set, rather than running `git pull origin main` every time you want to pull down changes to your local repo, you can just run `git pull` because `git` now knows what the upstream branch is. here is a stackoverflow post that goes into more detail.

Clone

Typically heard in reference to "cloning a repo". Cloning a repo is the act of downloading and copying a repository to your local machine, usually from a hosting platform like GitHub.

To clone a GitHub repo, you will need Read access to the repository. If you’ve setup git to use SSH keys, you can clone a repository as follows.

git clone git@github.com:TheDataMine/the-examples-book.git

If you setup git using a credential helper and HTTPS, you can clone a repository as follows.

git clone https://github.com/TheDataMine/the-examples-book.git

Both commands will copy the entirety of the repository in your current working directory (including the .git folder).

Add

New files added to a repo are not automatically tracked. If you modify an untracked file, those changes are not recorded in the .git folder. If you modify a tracked file, any changes saved to disk are tracked and noted by git, and automatically added to the staging area, ready to be committed.

git add adds a file or folder to the staging area, and begins tracking. To add a new file to the staging area, run the following.

git add my_file.txt

To add everything in the root directory to staging, run the following.

git add .

git add respects the .gitignore file in the root of the repo. The .gitignore is a specially named file with a pattern on each line that tells git which files to ignore and not track. A common example of a file that should not be tracked is a .env file with sensitive credentials.

Commit

A single unit of change, which could be to a single file, or multiple files. Commits allow users to track changes made to the project throughout time. In an ideal world, commits should be accompanied by a succinct message with a description of what changes were made and why.

To commit a change to the local repository, simply modify the file or files and save them to disk as you normally would. If the files are currently being tracked, git will "see" the changes and mark the file(s) as modified. Then, just commit the changes.

git commit -m "My succinct commit message."

Diff

To get a list of changes between the current, staged changes and the most recent commit, simply run.

git diff

Pull

git pull "pulls down" the changes made to the remote repo to your local repo. For example, let’s say we have Alice and Bob working on a project together. Alice made a change to the project and updated GitHub with all of the changes she made. Bob wants to update his local repo on his computer to be up-to-date. In order to do so, Bob runs git pull, and assuming Bob hasn’t made any conflicting changes locally, the changes Alice made will get merged into Bob’s local repo.

In order to use git pull, your current working directory should be inside of the local repo.

Push

git push is the symbolic opposite of git pull. git push takes your local commits and updates the remote repo so the rest of the team can work with the latest and greatest.

In order to use git push, your current working directory should be inside of the local repo.

Branch

A branch is just a copy of the repository within the repository. Branches enable a logical separation from the live version (usually main or master), to enable freedom of work without fear of messing something up. Typically your default branch is named master or main. You can create as many branches as you want within a repository, and switch between them using git checkout. When creating a new branch, you will be making a copy of a currently existing branch — often times this will be the main branch.

One common example of using branches would be what are sometimes referred to as "feature" branches. A feature branch is a branch created with the specific purpose of developing a feature on it, which can later be merged into the main branch.

To create a new branch called my-branch, first, checkout the branch from which you’d like to branch off of, for example, main.

git checkout main

You can confirm which branch is live by looking for the asterisk after running the following.

git branch

Next, create the branch.

git branch my-branch

Once the branch is created, you can switch to it.

git checkout my-branch

It is very common to need to create a new branch and immediately switch to that branch. To do so, you can run.

git checkout -b my-new-branch

Checkout

git checkout is the command that allows you to switch between different branches. To switch to a branch called "my-branch" simply run the following.

git checkout my-branch

Upon switching to my-branch, all of the files and folders on your local machine will change to match the code and files on that branch. If my-branch had a drastically different file/folder structure than my-other-branch, upon switching branches the files and folders will appear and disappear on your local machine.

Merge

Merging is the process of combining the changes and commits from one branch or fork to another. Ultimately, all accepted modifications made on other (non-live) branches need to be merged into the live branch.

To merge a branch called my-branch into the main branch, you must first switch the branch you want to merge into. In this case that is the main branch.

git checkout main

Then, it is as straightforward as running the merge command.

git merge my-branch

When there is a conflict, this will not be so straightforward. Please see the an example of resolving a conflict in the GitHub Desktop section.