We have read/write access to the Git repository available for maintainers and significant developers.
Our web pages are managed via git.
We provide authenticated access via the SSH protocol. This needs to be sponsored by an existing maintainer (someone with "write after approval" is not sufficient).
If you already have an account on sourceware.org / gcc.gnu.org, ask
email@example.com to add access to the GCC repository.
Include the name of your sponsor and CC: her.
If you do not have an account yet, use this form,
again specifying your sponsor.
We will then provision you on
gcc.gnu.org and inform you by mail. At this point,
check out a tree using the instructions below and add yourself
to the MAINTAINERS file. Note: Your first and last names must
be exactly the same between your account on gcc.gnu.org and the
MAINTAINERS file. Place your name in the correct section following
the conventions specified in the file (e.g. "Write After Approval"
is "last name alphabetical order").
Then produce a diff to that file and circulate it to the
gcc-patches list, whilst also checking in your change to
test write access (approval from the mailing list is not needed in this
one case). For all other changes, please be sure to follow the write
access policies below.
Once your account has been set up, check out the GCC sources by issuing the command:
git clone git+ssh://firstname.lastname@example.org/git/gcc.git gcc
where username is your user name at gcc.gnu.org.
It is also possible to convert an existing Git tree to use SSH by
git remote set-url origin git+ssh://email@example.com/git/gcc.git
To avoid the nuisance of having to supply your passphrase for each
operation, you may want to use
To avoid messages about (lack of) X11 forwarding, put in your $HOME/.ssh/config an entry like:
Git needs to know your name and email address. If you have not already configured those in $HOME/.gitconfig, do:
git config --global user.name "Your Name"
git config --global user.email "Your Email Address"
If you wish to use a different name or email address for GCC
commits from that in $HOME/.gitconfig, you can configure
that in an individual Git tree using a similar command
The GCC project grants developers various levels of write access to and review authority over the GCC master sources. We have not put any technical enforcement in place, rather we rely on everyone to follow the appropriate policies.
A limited number of developers have global review permission and can approve other people's changes to any part of the compiler.
This is for people who have primary responsibility for ports, front ends, or other specific aspects of the compiler. These folks are allowed to make changes to areas they maintain and related documentation, web pages, and test cases (and target conditionals) without approval from anyone else, and approve other people's changes in those areas. They must get approval for changes elsewhere in the compiler.
Maintainers of a port maintain the relevant files in
gcc/config, documentation, web pages, and test cases
and aspects of these relevant to that port. Port maintainers do
not have approval rights beyond this.
This is similar to localized write permission, except that reviewers required approval for their own changes.
This is folks that make regular contributions, but do not fall into one of the previous categories. People with write after approval need to submit their patches to the list; once the patches have been approved by the appropriate maintainers the patches may be checked in. The steering committee or a well-established GCC maintainer (including reviewers) can approve for write access any person with GNU copyright assignment papers in place and known to submit good patches.
The list of folks with write access to the repository can be found in the MAINTAINERS file in the GCC distribution.
When you have checked in a patch exactly as it has been approved, you do not need to tell that to people -- including the approver. People interested in when a particular patch is committed can check Git or the gcc-cvs list.
The following changes can be made by everyone with write access:
Obvious fixes can be committed without prior approval. Just check
in the fix and copy it to
gcc-patches. A good test to
determine whether a fix is obvious:
will the person who objects to
my work the most be able to find a fault with my fix? If the fix
is later found to be faulty, it can always be rolled back. We don't
want to get overly restrictive about checkin policies.
Similarly, no outside approval is needed to revert a patch that you checked in.
Importing files maintained outside the tree from their official versions.
Creating and using a branch for development, including outside the parts of the compiler one maintains, provided that changes on the branch have copyright assignments on file. Merging such developments back to the mainline still needs approval in the usual way.
All changes must be tested according to the instructions for testing patches before they are checked in. If you wrote the patch yourself, you should test it yourself, unless there is a reason why someone else must do it for you (for instance, if you are fixing a problem on a system you do not have access to). If you are checking in a patch for someone else, you only need to test it if they did not.
You must test exactly the change you intend to check in; it is not good enough to have tested an earlier variant. (Unless the only changes from the earlier variant are formatting and comment changes; if there are any changes to the code itself you should re-bootstrap.) It is a good idea to re-test patches which were submitted a long time ago before applying them, even if nothing appears to have changed.
When you post your change to
gcc-patches, state the
canonical name(s) of the platform(s) you used for testing.
These rules are designed to ensure that checked-in code does not contain bugs that prevent other people from continuing to get their work done. There will always be bugs, but these rules help to minimize the amount of time where the tree does not build at all. Repeated failure to adhere to these rules could result in the revocation of check-in privileges by the Steering Committee.
The following is meant to provide a very quick overview of how to check in a change. It is not meant to be a replacement for the Git documentation but instead a supplement. The Git documentation is available both as part of the Git source distribution, as well as on the Git website.
In all the commands listed below, you can give an explicit list of filenames to the git command. We recommend you list files explicitly when performing checkins to avoid accidental checkins of local code.
We prefer that each checkin be of a complete, single logical change, which may affect multiple files. The log message for that checkin should be a summary line (often the subject line of the email) followed by a blank line, then any discussion of the patch, and then the complete ChangeLog entry for the change. This makes it easier to correlate changes across files, and minimizes the time the repository is inconsistent. If you have several unrelated changes, you should check them in separately.
git pull" before attempting a checkin; this will save you a little time if someone else has modified the source tree since the last time you synced your sources.
git addto make Git aware of them.
git diff HEAD" after applying a patch to a local tree. Review the output to make sure that only the changes you wanted to check in will be checked in. Also check to see if the copyright dates need to be updated.
git commit" to check in the patch; either name the files to commit explicitly on the command line, or use
git commit -ato commit all modified files in the source tree (it is still necessary to use
git addfirst for any new files). If committing a patch for someone else, use
--author "Author Name <Author@Email.Address>"to credit the patch to its author. You can enter the log message via the "
-m" argument to commit, or wait for the editor window to appear and enter the log message in the editor window. If you use
-a, and without naming files explicitly, it will only commit files explicitly added with
git add, and will ignore any changes to those files made after you called
git addfor them.
git push. A message will be sent to the gcc-cvs mailing list indicating that a change was made. If
git pushgives an error because someone else has pushed their own changes to the same branch, do
git pull --rebasebefore trying
git pushagain. A typical error in this situation looks like:
To git+ssh://gcc.gnu.org/git/gcc.git ! [rejected] master -> master (fetch first) error: failed to push some refs to 'git+ssh://gcc.gnu.org/git/gcc.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
Git makes it very easy and cheap to create local branches for working on separate changes. To switch to a new local branch starting from your current HEAD, do
If the branch is based on GCC master, you can set it up to rebase automatically withgit checkout -b $BRANCH
git branch -u origin/master git config branch.$BRANCH.rebase true
To share a long-lived development branch publicly for collaboration with
other developers, you can use
git push as follows:
git push origin $BRANCH:devel/$BRANCH
Also, please document such branches at the list of development branches.
Shared development branches should not rebase; instead, merge master in by
hand occasionally as needed with a normal
git merge master. But
DO NOT then simply merge the branch back onto master; see below.
Every commit in the history of GCC master must follow the testing guidelines
above; when a development branch is ready to move into master, do not do a
simple git merge and push that onto master. Instead, invoke merge
git merge --squash $BRANCH
This readies a single normal commit with the effect of the merge. If the
merge can logically be divided into a series of commits that each pass testing,
you can use git tools like
git reset -p to break up the changes
accordingly. It may be easier to cherry-pick some smaller changes onto master
before doing the
For personal development branches that are already rebased on master you
don't need to
merge --squash squash, but still need to make sure
the commits on the branch satisfy the above rules for commits.
And then to enable it, dogit clone git://git.savannah.gnu.org/gnulib.git cd gnulib ./gnulib-tool --create-testdir --dir=/tmp/testdir123 git-merge-changelog cd /tmp/testdir123 ./configure make make install
git config --global merge.merge-changelog.name "GNU-style ChangeLog merge driver" git config --global merge.merge-changelog.driver "git-merge-changelog %O %A %B" echo "ChangeLog* merge=merge-changelog" >> $GCCSRCDIR/.git/info/attributes
refs/users/username/headswith tags in
refs/vendors/vendor-name/headswith tags in
Personal and vendor spaces are controlled by the individual user or vendor. Do not push changes to somebody else's space without their express permission. Rather than pushing to somebody else's branch, consider pushing to your own personal branch and having collaborators pull from there.
Scripts exist in the contrib directory to help manage these spaces.
This script will help set up your personal area. It will also define some aliases that might be useful when developing GCC. The script will first ask a number of questions:
me, but you can change this if you prefer. The script will add configuration information to allow local branches that start
me/<branch>to be pushed or pulled from your personal space in the gcc git repository on the server. Do not worry if you do not have an account on gcc.gnu.org. You will not be able to create a personal space on the server, but other settings configured by the script will still be useful.
If you have personal branches pushed to the gcc repository you can fetch
updates from your personal space by running
git fetch users/me (or whatever personal prefix you've
chosen). You can also push an already existing branch using
push users/me me/branch. Beware that if you have more than one
personal branch set up locally, simply typing
users/me will potentially push all personal branches based on
that remote. Use --dry-run to check that what will be pushed is what
you intend. The script
can be used to create a new personal branch which can be pushed and
pulled from the users/me remote.
The script also defines a few useful aliases that can be used with the repository:
--onelineoption to summarize the commit on a single line.
The final customization that the script makes is to add a diff rule so
git diff on a machine description file (a file
with the suffix
.md) will annotate
the diff hunk headers with the name of the pattern being modified (in
much the same way as C function names are used).
Vendor spaces are controlled by the named vendor. Unless you are affiliated with that vendor, do not push changes to that space without their express permission.
This script will set up a new 'remote' that can be used to access
the area used by a named vendor. You need to
contrib/gcc-git-customization.sh before you can use
The script requires one argument, the name of the vendor, and takes
--enable-push, to enable pushes to
be made to the space. If invoked with no arguments the script will
build a list of existing vendors from the server.
Once the script has been run, a new 'remote' will be configured with the
vendors/<vendor>. You can use this to fetch updates
to that vendor's branches.
To check out an existing vendor branch, you can use:
git checkout -b <vendor>/<topic> remotes/vendors/<vendor>/<topic>
This will create a tracking branch that can be updated with normal git
operations, such as
If you have set up push access, then the branch can similarly be pushed to using:
git push vendors/<vendor> <vendor>/<topic>
The script can be re-run with, or without
to enable, or disable push operations.
Before this script can be used
should be run to set up the vendor-specific workspace. This applies
even if the named vendor space does not yet exist on the server.
This script can be used to simplify the task of creating an initial
vendor branch. The script takes two arguments, the name of the branch
to create (including the vendor name) and the start point. For example,
to create a
test branch under the vendor
run and starting from the most recent commit on
This will create the branch both locally and on the server, but will not check the branch out locally. You can do that afterwards withcontrib/git-add-vendor-branch.sh <vendor>/<topic> master
before this script can be used, your personal space access should be
set up by running
The script takes two arguments, the name of the new branch to create and a ref to create it from. The personal prefix for the new branch is optional and will be automatically added if omitted. For example, if your personal prefix is the default (me), then running:
contrib/git-add-user-branch.sh topic master
will set up a branch called
topic on the server and a
local branch called
me/topic that tracks it. The banch
can then be pushed using:
git push users/me me/topic
Your gcc.gnu.org account also receives e-mail (and is what you use for Bugzilla). If you ever need to change the address e-mail to firstname.lastname@example.org is forwarded to, you can easily do so using
ssh email@example.com email firstname.lastname@example.org
Similarly if you want to add a new SSH key to your account:
ssh email@example.com appendkey < KEYFILE
Or replace all your SSH keys:
ssh firstname.lastname@example.org replacekey < KEYFILE
Copyright (C) Free Software Foundation, Inc. Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.