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
admin-requests@sourceware.org to add access to the GCC repository.
Include the name of your sponsor and CC: them.
Otherwise use this form,
again specifying your sponsor.
We will then provision you 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"). If you do not have an FSF copyright assignment on file, also add yourself to the DCO section in the file.
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.
Check out the GCC sources by issuing the command:
git clone git+ssh://username@gcc.gnu.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
using git remote:
git remote set-url origin git+ssh://username@gcc.gnu.org/git/gcc.git
To avoid the nuisance of having to supply your passphrase for each
operation, you may want to use ssh-agent(1) and
ssh-add(1).
To avoid messages about (lack of) X11 forwarding, put in your $HOME/.ssh/config an entry like:
Host gcc.gnu.org
ForwardX11 no
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 similar invocations
without --global.
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 or DCO certification 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 or DCO certification. 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
add to 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 want will be checked in. Also 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 -a to commit all modified files in the source tree (it
is still necessary to use git add first 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 git commit without -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 add for them.git push.
A message will be sent to the gcc-cvs mailing list indicating that a
change was made. If git push gives an error because
someone else has pushed their own changes to the same branch,
do git pull --rebase before trying git push
again. 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
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
with --squash:
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 merge --squash.
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.
refs/users/username/heads with tags
in refs/users/username/tags.refs/vendors/vendor-name/heads with tags
in refs/vendors/vendor-name/tags.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 git
push users/me me/branch. Beware that if you have more than one
personal branch set up locally, simply typing git push
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 contrib/git-add-user-branch.sh
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:
--oneline option to summarize the commit on a single line.
git cherry-pick -x
and reverts all modifications of ChangeLog files (both from index
and conflicting files)The final customization that the script makes is to add a diff rule so
that running 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. 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
run contrib/gcc-git-customization.sh before you can use
this script.
The script requires one argument, the name of the vendor, and takes
one option, --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
name 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 git pull.
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 --enable-push
to enable, or disable push operations.
Before this script can be used contrib/git-fetch-vendor.sh
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 megacorp
run and starting from the most recent commit on master:
contrib/git-add-vendor-branch.sh <vendor>/<topic> master
git checkout or git worktree.
before this script can be used, your personal space access should be
set up by running contrib/gcc-git-customization.sh.
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 branch
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 username@gcc.gnu.org is forwarded to, you can easily do so using
ssh username@gcc.gnu.org email mynewaddress@example.com
Similarly if you want to add a new SSH key to your account:
ssh username@gcc.gnu.org appendkey < KEYFILE
Or replace all your SSH keys:
ssh username@gcc.gnu.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.
These pages are maintained by the GCC team. Last modified 2024-03-01.