1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions & Useful Tcl Commands
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
6.6. Tests
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Using Git and GitHub
7.3. Contributing to MacPorts
7.4. Port Update Policies
7.5. Updating Documentation
7.6. MacPorts Membership
7.7. The PortMgr Team
8. MacPorts Guide Glossary

7.2. Using Git and GitHub

The MacPorts project uses the Git distributed version control system to manage the code for the entire project. Our master repositories are hosted on GitHub.

We maintain public repositories for almost all our project code and documentation, including a GitHub repository for the MacPorts system itself, for the MacPorts ports, and even for the guide you are reading right now.

If you're not familiar with Git and need an introduction, we recommend the book Pro Git, by Scott Chacon and Ben Straub. The book is available for free online, and is published under a Creative Commons license.

You should feel free to fork any of our code repositories, make improvements to the code, and contribute them back to us via a GitHub pull request. We are grateful for improvements to absolutely everything, including new ports, fixes to ports, improvements to our base software, improvements to our documentation and our web site, or anything else you see.

The main steps for submitting a pull request are:

  1. Make your changes in your own Git repository:

    1. Fork the appropriate repository, say macports-ports.

    2. Create a branch for your changes.

    3. Make your changes.

      For changes to ports and code, please follow the information elsewhere in this guide, and test your changes carefully.

      Changes to Portfiles should also pass port lint.

    4. Commit your changes to your branch, making sure to follow the MacPorts standard for commit messages.

    5. Be sure to rebase your changes so as to minimize the number of commits. Ideally, you should have just one.

      (There are exceptions. If you have several unrelated fixes, or you're changing multiple packages, etc., you might need more than one commit. The point is to minimize them, ideally with one commit per logical change.)

  2. Push the change branch to your own GitHub repository.

  3. Make a pull request from your branch in your own git repository to the appropriate MacPorts repository.

    You can do this on the appropriate GitHub page. For example, you can request a pull of a Portfile on the macports-ports repository pull request page.

  4. Go through the process of waiting for the CI system to build your new port, receiving feedback from our team, possibly being asked to make changes to your requested pull, and making those changes. (If you are asked for additional changes, please squish them to avoid unnecessary commits.)

We try to process pull requests very quickly. If you do not see activity on your request within a few days, please feel free to get in touch with us on the mailing list to request a review and/or commit. Please include a link to the pull request in your email.