Skip to content


Ross Bencina edited this page Mar 31, 2023 · 16 revisions

Using Git with PortAudio

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.

  1. Make a private "fork" of the main PortAudio repository.
  2. Working on your fork, create a branch and make your changes in one or more commits.
  3. When your work is ready you can "push" your changes to GitHub.
  4. Create a "Pull Request" and ask for a review.
  5. After it is approved your changes will be rebased and merged.
  6. When you want to make more changes, sync your fork to the main repository and go back to step 2.

Getting the Source Code

Please make a private fork of the main repository and then clone it. You only need to do this once.

  1. Visit this page to see the main repository.
  2. Click on the "Fork" button near the top right of the page to create your private fork.
  3. Visit your private repository page on GitHub.
  4. Click on the green "v Code" button and make a copy of the URL.
  5. In a Terminal window, cd to where you want the code
  6. Enter "git clone" then paste the URL. For example:
git clone{your_account}/portaudio.git
cd portaudio

Specifying the Upstream Remote

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
git remote -v

Getting the Latest Code

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.

Making a Change

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

Creating a Pull Request

Now go to GitHub and create a Pull Request for your branch into master by visiting

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.

Modifying a 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.

Submitting the Merge Request

After it has been approved, we will merge your changes.

Cleaning Up

When you are certain that the merge is complete, you can delete the branch in your local repository:

git branch -D fix123-glitches

Syncing your Fork

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
Clone this wiki locally