-
Notifications
You must be signed in to change notification settings - Fork 3
Git tutorial for MTRX 3700 Major Project
This tutorial only covers the absolute basics required to use Git. It is tailored specifically to the Mechatronics 3 Major Project (2016) although it is probably highly applicable as a general guide. It covers using Git from the command line, not GUI methods.
This guide might also not be 100% accurate, so please shoot me a message if you see anything that needs changing!
This tutorial assumes that some wizard has already made a Git repository (repo) on GitHub (or elsewhere).
Install Git here
I'm not sure but I think it will automatically install Git Bash as well. If not, you probably want to install it. Git Bash is just another command line program like the built in Windows CMD, but it gives you nice colour coding on stuff.
Navigate to the directory that you want your project folder to be in. Do this using the "cd" and "dir" (or "ls" if using Git Bash) commands. Type "dir" or "ls" to show what folders/files are in your current directory ("ls" colour codes the names). Then use:
cd folder_name
to go inside the folder.
Press your "tab" key to autocomplete words (the command line program autocompletes the word if what you have already typed is unique). If you need to go back up a level, use:
cd ../
Once you are in your desired folder, type:
git clone https://github.com/user/repo_name
or wherever your repository is stored. You will then have to type in your GitHub login, and then wait a few seconds for the online GitHub repository to be automatically copied to your current folder. Congratulations, you're now ready to code!
Before you code, you might want to switch to the non master branch, or make a new branch. See the "Branching" section below.
To code, simply open up MPLAB (or whatever else you use) and code as you normally would. At the end of your session after you've saved your files, (or just every so often is better practice), you'll want to "commit" your changes, i.e. tell Git that the changes/additions that you've made to your code should be permanently archived. This is sort of like copying your project into another folder as a backup.
To check which files have been changed, been added, etc, type:
git status
To commit your changes:
git commit -a -m "your message here"
The "-a" means that you want to commit all of your changes. Make sure that
your commit messages properly explain what you have done! Especially if you are
planning to merge your changes to the master branch (more on branches later).
To upload your changes to Git:
git push origin branch_name_here
Someone else might work on other parts of the code at different/the same time as you. In this case, you want to "pull" the origin (GitHub) copy before you do any coding. You won't be able to push to the origin copy until you pull the origin changes.
To update your local copy to the online (origin) copy:
git pull origin branch_name_here (usually master or the branch that you've been working on)
This will add/merge any changes made by others to your local repository, i.e. your actual files that you're working on! This is why Git is so incredible, as both version control and to allow you to simultaneously work on the same project with others. If there are any clashes (i.e. you've both made changes to similar areas of the same files), then you will have to manually resolve these. This tutorial won't cover how to do that.
Another way to pull is by using the "fetch" and "merge" commands:
git fetch origin branch_name_here
Followed by:
git merge origin branch_name_here
Is equivalent to using "pull". "fetch" retrieves all the changes made to the origin copy without altering your local copy. "merge" then alters your local copy with the changes that were fetched. You can usually get away with not typing "origin branch_name_here" but this is bad practice in case the program assumes one name and you mean another name.
"Committing" only tells your local git directory which changes you have chosen to confirm. "Pushing" uploads your locally commited changes to the Git server on GitHub (also known as the origin).
Branching is great because we are allowed unlimited branches, and it means that you have a chance to review any changes you make before merging it with the master copy. That means that if you mess up anything, it won't affect the master branch and we don't have to restore previous versions of the master (although fear not, restoring previous versions is easily doable).
To create a new branch:
git branch branch_name_here
To switch to an existing branch:
git checkout branch_name_here
Usual procedure is:
-
Navigate to your local Git directory from the command line using "cd" and "dir" (or "ls" if using Git Bash) commands.
-
Make sure you are working in the right branch by using:
git checkout branch_name_here
which makes you go to the branch that you want to work in. If you want to start a new branch from the master copy:
git checkout origin master
git pull origin master (If your local master copy is not up to date)
git branch branch_name_here
git checkout branch_name_here
3. Make sure your local copy is up to date with the origin:
git pull origin branch_name_here
4. Do all your coding
5. Check what changes you have made by using:
git status
6. Now commit and push your changes:
git commit -a -m "Commit message"
git push origin branch_name_here
Usually you don't want to push to the master branch, you want to work in, and push to your own branches. Push to the master only when you are sure your code is both working, well commented, and follows the coding standard.
There's a lot more to Git than what you just went through, but hopefully this is enough to get you on your feet and coding blissfully knowing that you don't need to keep track of your files manually ever again!
You also want to add a .gitignore file to your directory. This will tell Git which files it doesn't need to track, which saves time when you commit and push, and makes your command line less cluttered when using commands like "git status". The .gitignore file that I use for the major project is in this repository.
If you change your .gitignore (or add one when you didn't previously have one) then you'll need to tell Git to stop tracking some files. Do this using these commands:
git rm -r --cached .
git add .
git commit -m "Removes all files in .gitignore"
To do