GitHub Basics¶
What is GitHub?¶
GitHub is a code hosting platform for version control, backups and collaboration. It lets you and others work together on projects from anywhere.
Getting Started¶
Procedure¶
If you haven’t already, create a GitHub account.
On a browser, navigate to the PiCar GitHub Repository
Fork
the repo to create a copy of the master PiCar repo on your account.Under your repositories navigate to your version of the PiCar repo.
Clone
(download) the repo to your computer- Windows
- Download and install GitHub Desktop
- Login to your GitHub account
- Linux / Mac
- Copy the cloning link from your forked repo.
- Install Git:
sudo apt-get install git
- Make a new directory and navigate to it:
mkdir projects/github cd projects/github
- Clone the repo (replace
<username>
with your GitHub username)
git clone https://github.com/<username>/PiCar.git
Once you have made changes to the code or documentation, you need to commit the changes to the remote repo.
- Windows
- GitHub Desktop will automatically track changes you have made to the local repo.
- Click on the
pull
repository icon to update your local branch with the remote branch - Enter a commit message and hit the
Commit
button - Click on the
push
repository icon to update the remote branch with your local branch
- Linux / MacOS
- Inside the PiCar repository, using terminal:
git pull git add * git commit -m "your message here"
git pull
updates your local repo with the remote repogit add *
checks your local repo for changes and aggregates them for commitsgit commit
saves the new version and has a unique hash identifier- If you want to find that hash, you can use
git rev-parse --short HEAD
to fetch it.
Note
It is helpful to leave useful commit messages so that other contributors can see what you have done.
Push your changes to the master branch of your forked repo.
git push
- It will prompt you for your username and password, enter them.
Once the local changes have been pushed to remote successfully, go back to the original Picar GitHub Repository.
Click on
Pull Requests
>>New Pull Request
>>Compare against forks
The base fork should be
xz-group/PiCar
; change the headfork to<username>/PiCar
You can see what changes (additions and deletions) will be created with the Pull Request. Add a title and a short description and submit the Pull Request.
If you are a direct contributor on the main repo, you can navigate to Picar GitHub Repository >>
Pull Requests
>>Merge Pull Request
as long as there are no conflicts. If you’re not a direct contributor, you will need to wait until your Pull Request is merged with the master branch.
Note
Google and StackOverflow are your friends. Use them when you run into an issue with git (merge conflicts, etc.).
Syncing a Fork¶
If the main branch of the repository is ahead of your forked repo, you will need to sync your repo with the main one.
Navigate to the directory containing your forked repo.
Add a new remote called
upstream
which essentially points to the main repository:git remote add upstream https://github.com/xz-group/PiCar.git
Verify the remotes:
git remote -v
You should see something like:
origin https://github.com/username/PiCar.git (fetch) origin https://github.com/username/PiCar.git (push) upstream https://github.com/xz-group/PiCar.git (fetch) upstream https://github.com/xz-group/PiCar.git (push)
Grab the latest version of the
upstream
remote:git fetch upstream
Merge your local branch with
upstream
:git checkout master git merge upstream/master
Warning
If there are conflicts between your local repo due to you having changed files that have other commits in the main repo, you will have to fix those conflicts before being able to merge.
Push your changes to your
remote
repository:git push origin master
After making changes, submit a pull request as usual.