-
Notifications
You must be signed in to change notification settings - Fork 305
UsingTheGitRepository
This page has brief instructions for using Git. Git is extremely powerful so it is worth learning more about Git. Here are some links to more information.
Here are the basic steps. We will go into more detail below.
- Make a private "fork" of the main PortAudio repository.
- Working on your fork, create a branch and make your changes in one or more commits.
- When your work is ready you can "push" your changes to GitHub.
- Create a "Pull Request" and ask for a review.
- After it is approved your changes will be rebased and merged.
- When you want to make more changes, sync your fork to the main repository and go back to step 2.
Please make a private fork of the main repository and then clone it. You only need to do this once.
- Visit this page to see the main repository.
- Click on the "Fork" button near the top right of the page to create your private fork.
- Visit your private repository page on GitHub.
- Click on the green "v Code" button and make a copy of the URL.
- In a Terminal window, cd to where you want the code
- Enter "git clone" then paste the URL. For example:
git clone https://github.com/{your_account}/portaudio.git
cd portaudio
ls
You should specify that PortAudio is the upstream remote repository of your private branch. That will make it easier to push changes and to sync with the latest version.
git remote -v
git remote add upstream https://github.com/PortAudio/portaudio.git
git remote -v
Before you make any changes, make sure that your local repository is synchronised with your own remote and with the PortAudio upstream remote. First, pull down changes from your own remote fork (usually called origin).
git checkout master
git pull origin
Then merge any recent updates from the upstream repo. (If you followed the instructions above, upstream will be set to the public PortAudio project repository.)
git fetch upstream master
git merge upstream/master
Now you have the latest code and you are ready to make a change.
If this simple process fails see "Syncing your Fork" below. It covers rebasing an existing branch to bring in new changes from master.
Before making a change, you should start a new branch. Usually your branch will branch off of master. So start by checking out master.
cd portaudio
git checkout master
But you should never work in the master branch. If you are working on fixing a ticketed bug, eg. #123, you could name the branch fix123-glitches. To start a branch named "fix123-glitches", enter:
git checkout -b fix123-glitches
You can see a list of current branches:
git branch
Make changes to the code using your favorite text editor or IDE. Then to see what is changed enter:
git status
git diff
After testing, you can stage these changes and make them ready to be committed. You can either add individual files by filename or by folder. Or add everything under the current directory using a dot:
git add .
git status
Now commit the changes to your local repository.
git commit
You will be asked to enter a change log. Please put a summary on the first line. Then leave a blank line. Then add more text.
Now you can push your "fix123-glitches" branch to GitHub.
git diff HEAD^
git push origin fix123-glitches
Instead of the previous command, you may wish to use the --set-upstream flag to set the remote as upstream:
git push --set-upstream origin fix123-glitches
If you do it that way, you can push further commits to upstream with the simple command:
git push origin
Now go to GitHub and create a Pull Request for your branch into master by visiting https://github.com/PortAudio/portaudio/pulls
You will see a suggestion box for creating a Pull Request.
After creating a Pull Request, please ask for a code review. You can send an email to the PortAudio mail list along with a link to the Pull Request.
If your request is approved then we will merge it. But you may be asked to make a change. Go back to the same branch:
git checkout fix123-glitches
Edit the files as needed. Then add and make a new commit. Do not use "commit --amend" once you have pushed a commit. That will cause the review comments to be lost.
git status
git add .
git commit
git push origin fix123-glitches
Your latest change will be a new commit in the same Pull Request. Do not use --force because it can cause other peoples work to be discarded.
After it has been approved, we will merge your changes.
When you are certain that the merge is complete, you can delete the branch in your local repository:
git branch -D fix123-glitches
You should keep your private fork up-to-date with the main repository. If you drift too far from the current code then it can become hard to synchronize later.
When we synchronize we want to "rebase" our changes on top of the current HEAD. This will avoid making "merge commits", which can clutter a repository.
cd portaudio
git status # make sure everything is committed
git checkout master
git pull --rebase upstream master
You may have a merge conflict when you rebase. That can happen if two people are editing the same file.
If so then the rebase will pause in the middle. Then you must carefully untangle the conflict. Edit the conflicting file and then look for "HEAD" in the file. Be careful not do delete or damage other peoples work.
When you are satisfied with the changes use "git add" to restage the file(s) and then enter:
git status
git rebase --continue
If you get hopelessly messed up and wish you had never started rebasing then enter:
git rebase --abort
After rebasing you can sync your repository on GitHub by entering:
git push origin master