Sysadmin/GitKdeOrgManual

Overview of facilities

• KDE Identity (identity.kde.org)

Account management; notably managing your SSH public keys for read-write developer access.

• git.kde.org

Serves up the repositories, via git:// for anonymous read access and via SSH (on both ports 22 and 443) for read-write developer access (read-only access via HTTP is on the way).

• KDE Projects (projects.kde.org)

Central project hub and primary repository browser.

• gitweb.kde.org

Alternative repository browser. At present the only way to view personal clones of project repositories and personal scratch repositories (see below), however the former are planned to appear in projects.kde.org in the future.

• ReviewBoard (git.reviewboard.kde.org)

Patch review (account sign-up via KDE Identity).

• commits.kde.org

Provides git commit "short URLs", redirecting to KDE Projects and gitweb.kde.org pages as appropriate (example).

How to get read-write developer access

KDE developer accounts are managed through KDE Identity. If you already have a KDE SVN developer account, it has been imported into KDE Identity and you may use the Password Reset feature to set a password and manage your SSH public keys. If you don't have a developer account yet, you can request Developer Access in the website's menu upon registering and logging into your account.

Overview of repository URL schemes

URL prefixes

Anonymous read-only access uses the following URL prefix:

 git://git.kde.org/

Read-write developer access uses this prefix instead:

 [email protected]:

Repository paths

Following the prefix, here are the path schemes for different types of repositories:

• <project identifier>

A KDE project repository, be it part of the KDE SC, KDE Extragear or KDE Playground.

• websites/<address sans leading www. and dots replaced by dashes>

A KDE website project, e.g. websites/projects-kde-org.

• sysadmin/<repository name>

Non-public repositories used by KDE's sysadmin team.

• clones/<original repository path>/<KDE Identity user name>/<user-chosen repository name>

Personal clones of project repositories, e.g. clones/konversation/hein/morecowbell or clones/websites/projects-kde-org/hein/pluginwork (more below).

• scratch/<KDE identity user name>/<user-chosen repository name>

Personal scratch repositories are a means to start a new project or just to store your favorite .bashrc in a safe location: anything is allowed so long as it is related to KDE or your work for KDE in some way (more below).

Server-side commands

git.kde.org understands several server-side commands that can be used on the command line via SSH in this fashion:

ssh [email protected] <command> [parameters]

The following is a list of the commands that are currently available, broadly divided into categories according to their purpose.

Commands for information retrieval

• info (link here)

Shows a table of repository paths and path patterns you have the permission to see along with details about your access rights to them.

A brief legend for the permission flags shown in the listing:

• @R - Read permissions.
• @W - Write permissions.
• @C - Create permissions (e.g. the initial push to a newly-created repo).

If you want to list actual repositories corresponding to patterns listed by info, such as your personal scratch repositories, see the expand command described next.

• expand [regex] (link here)

Like info above, but actually walks through the repositories to verify the information. It's much slower as a result, and should be used if info doesn't provide enough information. For example, info will list your personal scratch space only in the form of a pattern while expand can list the actual repositories located there.

The output is limited to about 20 rows. The optional regex parameter allows you to filter the listing.

• who-pushed <repository path> <commit sha1 hash> (link here)

Shows the KDE Identity user name of the contributor who pushed the specified commit to the specified repository.

Commands to manage personal repositories

• clone <path to source repository> <clone name> (link here)

Can be used to make a personal clone of a project repository.

An example:

 ssh [email protected] clone konversation mykonvi

This results in a clone at clones/konversation/<your KDE Identity user name>/mykonvi.

A second example with a longer source repository path:

 ssh [email protected] clone websites/projects-kde-org newtheme

This results in a clone at clones/websites/projects-kde-org/<your KDE Identity user name>/newtheme.

More on personal clones here.

• destroy <repository path> (link here)

Used to delete a personal clone of a project repository or a personal scratch repository. Requires the repository to be unlocked first using the unlock command and will additionally ask for confirmation. See also the trash command as an alternative to outright and irrevocable deletion.

• lock <repository path> (link here)

Locks a repository, causing the detroy command to deny deleting it.

Newly-created repositories are locked by default.

• unlock <repository path> (link here)

Unlocks a repository, making it possible to delete it using the detroy command.

Commands to manage the personal trash area

• trash <repository path> (link here)

Moves a repository to the personal trash area, creating an entry in the form <repository path>/<timestamp> there. The timestamps, which have second precision, make it possible to have more than one version of a repository in the trash area at the same time.

Note: Entries in the personal trash area are automatically removed after 28 days!

• restore <trash area entry> (link here)

Restores an entry from the personal trash area (see the list-trash command below for how to list the contents of your personal trash area).

restore will deny restoring an entry if doing so would overwrite an existing repository.

• list-trash (link here)

Lists all entries in the personal trash area, in the form <repository path>/<timestamp>.

Commands for repository importing

• hooks-enable <repository path> (link here)

Available only to repository and system administrators, this command enables hook scripts that git.kde.org will then execute during a push operation to the specified repository. The specified repository must be a project repository; the hook scripts are not available to personal repositories.

New, empty repositories start out with the hook scripts disabled so you can import large numbers of old commits without them being sent to the kde-commits mailing list and CIA.vc, and without commit message keywords (BUG, CCMAIL, etc.) being processed. Note that while the hook scripts are disabled only repository admins can push commits to a repository.

See also the hooks-disable command.

Commands for system administrators

• sudo <KDE Identity user name> <command> (link here)

Used by system administrators to run one of the above as another user.

• able <en|dis> <@all|repository path> (link here)

Used by system administrators to enable or disable writes to particular repositories or all repositories, for maintenance.

• hooks-disable <repository path> (link here)

Disables the hook scripts git.kde.org normally executes during a push operation to a project repository. While the hook scripts are disabled only repository administrators can push commits to a repository. Both system and repository administrators have the ability to reenable the hook scripts using the hooks-enable command.

• ohnoes <show|recover> <repository path> <gitref> (link here)

Used by system administrators to recover deleted branches or mistaken force pushes (rewinds).

Personal repositories

git.kde.org currently offers two types of personal repositories: Personal clones of project repositories and personal scratch repositories.

Personal clones of project repositories

A personal clone of a project repository can be created using the server-side clone command on the command line:

 ssh [email protected] clone <path to source repository> <clone name>

This will create a clone of the source repository at clones/<path to source repository>/<KDE Identity user name>/<clone name>. (See more examples of clone in action here.)

This scheme makes it very easy to locate all personal clones of a given project and should be preferred over making one in your personal scratch space. (In fact, the server-side clone command won't allow you to clone a project repository into your personal scratch space, but nothing technically prevents you from taking the detour of a local clone to achieve this.)

Personal clones of project repositories currently do not show up on KDE Projects, but we have plans to change that in the future. Until then, you can use gitweb.kde.org to browse these repositories.

Personal scratch repositories

Personal scratch repositories are a means to start a new project or just to store your favorite .bashrc in a safe location: anything is allowed so long as it is related to KDE or your work for KDE in some way.

Creating one is easily done by just pushing:

 git push --all [email protected]:scratch/<your KDE Identity user name>/<repo name of your choosing>

(Or you could use git remote add to add a remote to push to.)

Personal scratch repositories can be browsed on gitweb.kde.org.

If you feel your new project is ready for the wider world and/or wish to signal that it welcomes outside contributors, you may wish to promote it to the status of a KDE Playground project. KDE Playground project repositories are located at the top-level, i.e. the repository will be moved out of your scratch space and may have to be renamed in the event of a collision with an existing repository name. KDE Playground projects are featured on KDE Projects and covered by the kde-commits mailing list (and thus CommitFilter), LXR, the EBN and CIA, unlike personal scratch repositories.

To request your scratch repository be promoted to the status of a KDE Playground project, you currently need to file a sysadmin request. In the future we plan to provide a fully automated facility on KDE Projects.

Note that we have deliberately decided not to allow the direct creation of KDE Playground projects; the path to existence for a KDE Playground repository project always leads through a personal scratch space first. This is to give you the power to decide whether your project is ready, and also to force you to deliberate whether it truly is.

Deleting personal repositories

A personal repository can either be deleted outright and irrevocably by using the destroy command (which requires you to unlock it first to avoid accidental deletion), or you may move it to the personal trash area with the trash command.

Entries in the personal trash area are kept for 28 days, and can be resurrected at any moment during those 28 days by way of the restore command. You can list the current contents of your personal trash area with the list-trash command.

Using ReviewBoard and post-review

A very comfortable way of posting changes for review is ReviewBoard, where every git repository in KDE has its own project. There are some easy steps for posting a review without hassle.

Creating your changeset

To create your changeset, you probably want to work in a separate branch - or even in your clone. This is actually suggested and the proper way to do changesets in git. You can create any number of commits, amend them, and do whatever you want to do - it won't affect the next phases, as we will submit the whole branch for review.

Using post-review to post changes

Once you are done, it's time to post changes to reviewboard. The easiest and most comfortable way to do that is post-review, a handy command line tool which takes care of creating review requests for you.

Prerequisites

Those steps have to be done just the first time for configuring your repo, if needed.

First of all, you have to tell post-review about the KDE server. If your project does not ship with a .reviewboardrc file (encourage the project manager to do that!), the first thing you have to do is:

git config reviewboard.url http://git.reviewboard.kde.org

ReviewBoard accepts only anonymous git repositories (git://), so we need a remote for that. If your origin is already an anonymous git repository, you are already fine. Otherwise, you need to add another remote to complete the review phase. Let's suppose our project is Amarok, and our origin is [email protected]:amarok. We need to do:

git remote add anonupstream git://git.kde.org/amarok
git fetch anonupstream

Of course, if your origin remote was already a git:// address, just substitute "anonupstream" with "origin" in the rest of the tutorial.

Creating a review request

Now we have to tell ReviewBoard where our changesets generated. A good practice before doing that is rebasing your branch onto the branch you want to target for merge. So, supposing you want to target master, you would do

git rebase master

Of course, be sure that master is up-to-date with the remote before doing that!

You are now ready for posting changes. The post-review command should look something like this:

post-review --parent=master --tracking-branch=anonupstream/master

This command tells post-review that your branch is based upon master, and it is set to track the remote branch anonupstream/master. You can also give post-review some more arguments to avoid using the web interface later, have a look at post-review manual for more on that.

Once the command will be run, a web address will be shown in the terminal, carrying your review request.

Updating a review request

If you need to update a review request, you can invoke post-review with an additional -r argument, which should be the number of the review request you want to update. Supposing you want to update the review request #54, you would do:

post-review --parent=master --tracking-branch=anonupstream/master -r 54

Creating a ReviewBoard-compatible diff

In some rare cases, you simply want to generate a diff, and submit it to reviewboard later. You can do that by doing:

post-review --parent=master -n > your-patch.patch

Requesting project migrations from KDE SVN or Gitorious.org

To get your project moved from KDE SVN or Gitorious.org to git.kde.org, you have to file a sysadmin request providing the following information:

• The name and description of the project.
• The current location of the project.
• Its current or intended module (e.g. playground/utils or extragear/network).
• Which KDE Identity user name(s) should have admin rights to the repository and the entry on KDE Projects.
• The email address that the ReviewBoard group for the project should send emails to.
• The date and time the migration should take place (can be "asap").

When we have completed processing your request, there will be an empty repository at the chosen path (more here) that the repository admins can push the data into. Once you are done pushing everything to the repository, use the hooks-enable command to enable the commit hooks and allow write access to non-admins.