Git tutorial and policy

Git tutorial and policy

What is this document for?

To provide both a tutorial on the basics of git and a clear outline of our git policy. This will not be a deep dive into git. We already had some documentation on git policy but we wanted more details, partly to address milestone 1 feedback, and partly to address actual issues we’ve observed in our workflow.

Other resources

Atlassian has fantastic articles on git. I would recommend those for understanding specific git commands over the official git documentation.

⚠️ Danger: running unfamiliar git commands

When you come across git issues, you’ll often come across related stackoverflow posts. These can be great resources, but be wary of running git commands you do not understand!

Some examples to watch out for (from stackoverflow):

• git push --force, or git push -f : this can delete history from the remote repo, which is very dangerous.
• git reset : not always bad, but can cause you to lose commits.

What is a git repo?

git is a version control system. This means you can keep track of not only the current state of a project (i.e. all of the source code), but also all previous states too, and you can easily switch back and forth between these states.

The repository (aka repo) is the entire project containing all of your source code. Each team member will have their own local repo on their computer, while we all share a remote repo on github (or gitlab, or wherever else). The remote is often nicknamed origin. Note that a repo is really just a folder on your computer that has a special .git/ folder within it. This special folder is where git stores all of the information it needs to track our project. For example, see the .git/ folder listed in my local repo below.

If you’re curious, here’s what’s stored inside of the .git/ folder. The blue lines are sub-folders, and the white lines are just normal files. You don’t need to know this to use git!

Each team member’s local repo won’t necessarily be in exactly the same state as the remote repo at any given moment. This is what pushing and pulling are for, but we’ll discuss those later.

When you want to start a new project in git, you typically:

1. Create a new folder on your computer where all of your files will go.
2. Run git init within that folder. This creates that .git/ directory I mentioned earlier.
3. Optionally create a new blank repo on github. You can then set this as your local repo’s remote using git remote add origin https://www.github.com/username/reponame where "origin" is the nickname of the remote and the url points to the github repo.
4. Anyone else who wants to work on your project will then git clone https://github.com/Monash-FIT3170/Team4-Android-Talkback once to essentially download a local copy of the repo. You should only need to clone a repo once (per computer).

Git branches

git comes with the concept of branches. Your repo must always have at least one branch. The default branch is typically called main or master. You might create a new branch every time you want to implement a feature, or fix a bug. In which exact situations you make a new branch depends entirely on your team's preferences: large open-source projects will likely require you to create a new branch for even the smallest of changes, but smaller teams might find this cumbersome.