Git/Creating new repositories

< Git
Other languages:

This is designed to be a quick and dirty tutorial about how to create a new Git repository hosted by the Wikimedia Foundation. The tool being used as of June 2012 is Gerrit and you will need to be one of the people who are allowed to create new repositories.

Step 0: Read and understand Gerrit docs[edit]

Before attempting to create repositories, there are two sections of the Gerrit documentation that you definitely need to read and be familiar with :

Gerrit access controls
You almost always will be setting permissions after creating a new repository, so it's important to understand what each of the permissions means and how to use them
create-project command
You will be creating the repository via the command line, so make sure you've read and understand the various options available via the command line (especially the --parent and --owner switches!).

Step 1: Pick your repository name[edit]

Before you begin, make sure you have decided on a repository name that you do not want to change. Renaming repositories is near impossible (as of Gerrit v2.4) so you need to make sure you are happy with your repository name before you create it. Try to keep the name short, yet meaningful. Please note name must be made of either latin letters (a-z), roman numbers (0-9) or dashes ( - ).

Step 2: Pick your repository's home[edit]

For organization (and permission) purposes, we use top-level project names (like mediawiki/* or operations/*) to put repositories in. It's best to not create new top-level repositories without discussing it first, so the top-levels can be named and setup in a way that is useful and descriptive.

As an example, mediawiki/extensions/VisualEditor where mediawiki/extensions is the prefix used for any MediaWiki extension. If you are unsure, ask around, for example on wikitech-l.

Previously PHP libraries were created as top-level repositories, but now should be created under the mediawiki/libs/* namespace per T125031.

Step 3: Create the repository[edit]

Even though there's a way to create new repositories via the Gerrit web interface, please don't use that GUI. There's a couple of shortcomings[1], so please create the new repository via the command line. Let's say we were making a new repository called test/my-new-repo, so the command would be as follows:

ssh -p 29418 gerrit create-project --require-change-id --owner=MyGroup --parent=test --description='"My super awesome repository"' test/my-new-repo

Important Caveats[edit]

Setting the --parent switch is very important so you inherit the permissions from the containing repository. If you do not specify the parent, the parent defaults to All-Projects, which is nearly useless for most repositories. The parent can be adjusted via a Gerrit admin if you get it wrong, however.

Setting the --owner switch is even more important because if you do not set the owner of a repository to a group you are a member of (or that the intended user is a member of), you (or they) will be unable to adjust the permissions on your newly created repository (and you'll have to ask a Gerrit admin to fix that).

Step 4: Set permissions[edit]

In some cases, you may want to adjust permissions beyond what is inherited from the parent repository. Once the repo is created (and you are an Owner), you can then adjust the permissions via the Gerrit web UI. You will want to use the Gerrit documentation about access rights.

When done changing initial permissions, be sure to remove the "Project and Group Creators" group from the Owner permission, as they do not need it after rights are initially configured.

Step 5: Create .gitreview file[edit]

Once you've made your new repo, please be sure to add a .gitreview file in the root of the new repository. This is especially important for extensions, as failure to do so will break Translatewiki. A .gitreview file should look like:


The host and port should never need to be changed. "project" should be changed to match the repository you've just created. "defaultbranch" is the primary branch that you'll be submitting code to - usually this is master. "defaultrebase" disables the implicit rebasing `git review` does before submitting a change. Lots of repos find this behavior annoying, so you'll generally want to include this. It can be safely omitted, though.

Step 6: Setup mirror on Phabricator[edit]

Once you've done all of the above and have a working Git repository in Gerrit, you'll need to create it in Phabricator so we can replicate there.

  1. Create a new repository in Diffusion here.
  2. The "name" can be anything that describes the repository well.
  3. The callsign can be omitted, but please don't. It should be a short-ish string of letters that identifies the repository. Acronyms are great here.
  4. The short name should the same name as in Gerrit, with slashes replaced with dashes. This isn't required, but it aids in navigation. As an example: 'operations/puppet' would be 'operations-puppet'.
  5. Click on URIs, add a new URI.
    1. Set all URIs created by default by Diffusion to No I/O first (otherwise Phabricator won't let you add a new remote URI to observe).
    2. Create a new URI. Use the Gerrit replica anonymous https clone part without "git clone", i.e.
    3. Set the IO method to "Observe: Copy from a remote".
  6. Go back to the main repo page and click "Activate".

If you don't have permissions, speak to a #Repository-Admin in Phabricator and we can help you out.

Step 7: Create a repository in Github[edit]

In order for Gerrit to replicate the repository to Github, it first has to be manually created at . Replace slashes by dashes for the new name (just like for Phabricator).

Step 8: Register the extension submodule on mediawiki/{extensions,skins}.git[edit]

As a last step for mediawiki extensions and skins only, you should register the extension on mediawiki/extension.git or mediawiki/skins.git superprojects. Those are used by some maintenance tools and bots (for example, to keep track of extension.json updates or composer/package.json dependencies).

Importing from an existing repository[edit]

In case you need to import an existing repository, you will need to add the following permissions on refs/*:

  • Push
  • Create Reference
  • Create Annotated Tag
  • Create Signed Tag
  • Forge Author Identity
  • Forge Committer Identity

Then clone a mirror of the existing repository, and send all the references to gerrit:

$ git clone --mirror <path to existing repository> mirroring
$ cd mirroring
$ git remote add gerrit ssh://<gerrit repository name>
$ git push --mirror gerrit

There will be an error about refs/meta/config which holds the Gerrit repository configuration and can not be overwritten.


  1. Main drawback is inability to set the Owner, which can leave you locked out of your own brand new repository