- This tutorial will introduce you to some basic git commands.
- It will teach you just enough to be able collaborate with others on a shared coding project.
- It assumes you will be working with a team of people you know.
- To continue learning, refer to the links at the bottom of the tutorial.
➜ Check you have git installed
➜ Install Visual Studio Code (recommended)
Everyone in your team needs to complete this step independently.
➜ Navigate to https://github.com
➜ Click Sign up to register a free account
- Refer to the GitHub Documentation if you encounter issues
A repository is a bit like a folder that groups together items that belong in the same project. In Step 3 we'll give everyone in your team access to the same repository so they can work on the project together.
Only one person in your team needs to do this step.
➜ In the upper-right corner of any page, select +, then click New repository.
➜ In the "Repository name" box, type a short but descriptive name for your project.
- Your repository name should be lowercase, with words separated by "-"
- For example, "study-buddy-app"
➜ In the "Description" box, type a short description.
- For example, type "This repository is for a Study Buddy app."
➜ Select whether your repository will be Public or Private.
➜ Select Add a README file
➜ Click Create repository
In this step you'll add members of your team as collaborators on your project.
Only one person in your team needs to do this step.
➜ From your repository, click Settings
➜ Select Collaborators from the menu on the left Select Add People and search for your team members by Username, Full Name, or Email
For more information, refer to this section of the GitHub Documentation
➜ Before going further, take a look at the diagram below which describes some fundamental git concepts.
In this step, everyone in your team will make a "clone" of the remote repository in their local working directory. This will allow you to work on the codebase independently.
The remote repository can be thought of as a central source of truth, while your local repositories are where the work happens.
Later, we'll learn how to manage the workflow so that the remote repository on GitHub stays clean and up to date.
Everyone in your team needs to complete this step independently.
➜ In GitHub, from the Code tab of your repository, click Code
➜ Copy the HTTPS URL
➜ Open Visual Studio Code
➜ From the files Explorer tab, click Clone Repository
From Visual Studio Code there are a couple of ways you can clone a repository. In this tutorial, we'll use the Integrated Terminal method.
➜ Open an integrated terminal from Terminal -> New Terminal
➜ In the terminal, navigate to the place in your file system where you'd like to clone the repository
➜ Clone your repository with the following command:
git clone https://github.com/YOUR-NAME-OR-ORGANIZATION/YOUR-REPO-NAME
- In the above, you can paste the URL you copied earlier.
➜ Navigate into the new folder:
cd YOUR-REPO-NAME
➜ Then open it in Visual Studio Code:
code .
Having reached this step, you should all have a local copy of the remote repository in your working directory.
In this step, you'll each practice 'staging' and 'committing' a new file to the remote repository.
Everyone in your team needs to complete this step independently.
➜ From Visual Studio Code, with your project open, go to File > New File
➜ When prompted to enter a name for the file, call it your-name.md (replacing 'your-name' with your name)
- For example,
sorrel-harriet.md
➜ Inside the new file, write a joke or greeting for your team members
➜ Save your changes
➜ Open the Terminal (View > Terminal)
➜ Stage the new file for commit:
git add your-name.md
- This is like saying to git, "start watching this file"
➜ Commit the changes:
git commit
- This creates a record of the changes you've made in the project's version history. The set of changes is assigned a unique SHA-1 hash code which enables us to identify it in the future.
➜ Enter a commit message
- At this point, you'll be prompted to enter a commit message from a GNU editor.
- The commit message describes the change to your collaborators.
- This can be something like, "Adding new greeting feature"
- Exit the editor with
Ctrl+x,yto save changes, thenReturn
NB: For future reference, you can include the commit message in the commit command using the -m option:
git commit -m "some commit message"
➜ Push the new version to the remote repository:
git push origin main
- This step applies your changes to the remote repository.
➜ Visit your remote repository on GitHub.
➜ Under Commits, you should be able to see a summary of the changes that have been made to your repository. It should include changes made by other team members.
- Since you have all worked on separate files, git will have had no problem merging the changes you each made independently. Had you all worked on the same file, there would be potential for merge conflicts.
- Assuming the 'main' branch of the project is the one that contains deployable code, we don't want to risk messing it up while working on a set of changes.
- In the next few steps, we'll learn how we can safely work the code base without risking messing up the main branch.
- From now on, we'll think of the main branch as the 'trunk' (like a tree trunk). Whenever we want to make some changes, we should create a new 'branch' to do our work.
- After we've done our work, and are satisfied our code is well tested and contains no defects, we can then merge the branch back into the trunk (main).
- This workflow is called trunk based development (TBD). In TBD, branches should be shortlived (i.e. they not exist for more than a couple of days.) The code in the trunk should always be in a deployable state.
NB: For more information about TBD and alternative workflows, such as feature-based development, refer to the recommended resources and further reading.
By now, hopefully your team members have pushed changes to the remote repository.
To see their changes reflected in your local repository, you need to 'pull' them down.
➜ Update your local repository:
git pull
In this step you'll create a new branch to isolate your work from the trunk (main branch).
As is often the case, there are multiple ways of doing this. We will use the Integrated Terminal method, as this will give you experience with git commands.
➜ From the Terminal in Visual Studio Code, create a new branch:
git branch branch-name
- You should give your branch name a unique and descriptive name that will help others understand its purpose. For the purposes of this tutorial, call it
your-name-dev(for example,sorrel-dev)
NB: The above creates a branch from the currently checked out branch. In your case, this is main. However, if you were already working on another branch, it would create a branch off that branch...so do pay attention to which branch you are currently working on! To check which branch you're on, you can do:
git branch
➜ Switch to the new branch:
git checkout your-new-branch
➜ On the new branch you've created, create another markdown file. Call it your-name-feature.md or similar.
➜ Add, commit and push this file to your new branch:
git add your-name-feature.md
git commit -m "working on a new feature"
git push origin your-new-branch
➜ From GitHub, look under the branch dropdown menu to see that your new branch has been created:
Finally, let's assume you've now finished working on your new feature and are ready to merge it back into the trunk.
➜ Switch to the main branch again:
git checkout main
➜ Merge your branch into main:
git merge your-new-branch
Hopefully you won't get merge conflicts! If you do, you'll have to resolve them, and then commit the merge.
➜ Delete the working branch:
git branch -d your-new-branch
➜ Check it was deleted locally:
git branch
If you now look on GitHub, you will see the working branch is still listed there!
➜ To get rid of the working branch completely, do:
git push origin -d branch-name
➜ Refresh GitHub and check it has gone.
And that concludes Tutorial 1! You now have a simple workflow to use when collaborating on your codebase. You might not want to bother with branches at all, and instead commit all your changes to main. Either way would be reasonable for this project.
Before you can start working on your project for real, you might want to delete those markdown files we created in this tutorial...
➜ Remove a file from the git index and push the changes to remote:
git rm your-name-feature.md
git commit -m "removing an old feature"
git push origin main
- Using git with Visual Studio Code
- Thread discussing the differences between trunk based development (TBD) and gitflow
- Using GitHub Flow
- Eli Schleifer (2022) Git for trunk based development
- Trisha Gee (2023) Why I prefer trunk based development
- Jacob Schmitt (2023) Trunk vs Feature Based Development