A beginner's guide to Git

• 10 minutes to read

This tutorial walks you through the most common Git tasks on your local computer. We show the Git Bash command line and Visual Studio Code (VS Code) side-by-side.

Working locally has many benefits:

You can still be productive with no or bad internet connection. Long commute? No problem.
You get to choose the Markdown editor and customize it to your preferences.
You can leverage powerful search and file operations.

Other options:

Work exclusively in the browser on github.com.

Day 0

Install software
Fork/clone the repository

Tip

If you don't have Git installed, you will need to install Git first. You can find instructions on installing Git in the free Pro Git book, written by Scott Chacon and Ben Straub.

Clone repo

To clone means to create a copy of the repo (files and folders) on your local machine so that you can work with them.

To find the URL:

Browse to the repo on GitHub.
Select the Code tab.
Click to expand the green Code button.
Copy the HTTPS URL to the clipboard.

Git Bash command line
VS Code

Go to the folder you want to create the copy.
Run git clone [INSERT REPO URL]:
```
git clone https://github.com/SuperOfficeDocs/contribute.git
```
You can right-click to paste the URL to the command line.
Open the repo folder:
```
cd contribute
```

Starting the workday

At the beginning of the workday, it is good practice to always get the latest updates from the branch you are going to work on. This is called to pull.

Git Bash command line
VS Code

Go to the repo folder.
Run git pull:
```
git pull
```

Git Bash pull -screenshot

Go to a branch to do work

If you are going to resume work where you left off the previous day, congratulations! You're already good-to-go with the latest updates.

To start something new, you need a GitHub issue and a Git branch.

Let's assume the issue is already on the backlog and assigned to you.

Go to GitHub.
Move the issue from To do to In progress to let your peers know what you are working on.
Note the issue number.

You can now create a new branch:

Git Bash command line
VS Code

Go to the repo folder.
Run git switch:
```
git switch -c [INSERT NEW BRANCH NAME]
```
The -c means create. Follow branch naming conventions, starting with the issue number. For example, "256-release-notes-10.1.1".

Get new updates

During the workday, it might be a good idea to get additional updates from your colleagues. Simply pull on your current branch as you did earlier.

If your team is working on the same files, you might run into merge conflicts. More on handling these later. For now, here's a few tips to avoid conflicts:

Commit before you pull (or switch branches)
Pull before you push

If you're not ready to commit yet, you can stash the changes for later.

Saving your changes is a three-step process:

Save the changes to your local disk (normal Save file).
Save the changes to your local Git repo (the clone). In Git terms, this is to stage and commit.
- Stage (add) means to prepare the set of changes you want to add to Git version control.
- Commit means to create a snapshot of those changes, adding a new version of those files to the Git history.
Publish the changes to GitHub (sync to cloud). In Git terms, push.

Tip

Adding the issue number (for example #256) somewhere in the commit message automatically links your changes to the issue and lets others see what has been done.

Go to the repo folder.
Run git add:
```
git add .
```
The dot means add all changes. See also this how-to for more fine-grained staging.
Run git commit
```
git commit -m "[INSERT MESSAGE]"
```
The -m means message follows.

Publish the changes to GitHub

The last step before your team-mates see your updates is to sync to the cloud (push).

Git Bash command line
VS Code

Go to the repo folder.

Run git push

git push -u origin "[INSERT NEW BRANCH NAME]"

The -u means upstream.

Finish an issue

Go to the repo on GitHub.com. GitHub should detect the updated code and prompt you to make a pull request.
Click the Compare and create pull request button.

It might also look like this:
Fill in info such as title and description and select a reviewer.

In the description or comments section be sure to include the text "Resolves #[INSERT ISSUE NUMBER HERE]" where your previously created issue number is associated with this pull request.

Switch context - work on something else

Sometimes you'll need to suspend your current work in progress to deal with something else.

You're blocked waiting for someone else to do something or to get back to you.
Someone asked you to help them out on an urgent issue.
Someone requested your review on a pull request.

Stage and commit your changes.

If this is inconvenient, use Stash.
Switch to the main branch and pull.
Start a new issue or switch to an existing branch (and pull).

Switching between branches

Git Bash command line
VS Code

Go to the repo folder.
Switch to main and pull:
```
git switch main
git pull
```

Switch to the next branch and pull:

git switch "[INSERT BRANCH NAME]"
git pull

Before you clock off, clean up your desk so to speak. The longer you accumulate stuff locally, the harder it can get to sync up with your team eventually.

Also, I sleep better at night knowing my content is safe in the cloud and not just on my hard drive.

If you've worked on one issue only:

Share your updates one last time.
Initiate the review process (if relevant).
Update status and/or comment on the issue on GitHub to keep your team in the loop.

If you switched context, you should revisit those other branches to wrap up those as well.