====== Xfce.org Git Infrastructure ======

**This documentation is obsolete ! Please see http://docs.xfce.org/contribute/dev/start**



===== Account Setup =====

If you have an xfce.org Subversion account that does **not** include ssh access (that is, you check in using https), you will need to apply to get your account converted [[https://releases.xfce.org/login/request|here]].  Fill out the form with the same info you used previously, but remember to include a ssh public key in the appropriate box. Translators: [[dev:howto:git#translator_access|see here]].

If you used the "old" git.xfce.org, and used clone/push URLs like "''git@git.xfce.org:$USER/$MODULE''", then you should follow the directions above as well.

You will receive an email with instructions when your account is ready.

If you already have a ssh shell account on git.xfce.org (aka mocha.xfce.org), your account information has not been changed and you are ready to go.

If you do not have an xfce.org account at all, you'll need to request one as explained on [[/contribute#getting_a_git_account|that page]].

===== Usage =====

**If you are uncertain of the clone URL to use for a particular module, please find and click on the module in the listing in [[http://git.xfce.org/|CGit]].  Clone URLs are listed at the bottom of the page for each module.**

In short:  If you don't have a ssh account and just want a read-only copy of the source, you'll want to do:

<code>git clone git://git.xfce.org/$TYPE/$MODULE</code>

or

<code>git clone http://git.xfce.org/$TYPE/$MODULE</code>

''$TYPE'' is one of 'apps', 'bindings', 'xfce', etc.  See the italicized group names in the [[http://git.xfce.org/|CGit index]].

Committers, see below.

===== Committers =====

Before you even think about pushing changes, you must set your name and email address to something valid in your **local** Git config:

<code>git config --global user.name "J. Random Hacker"
git config --global user.email jrandom@example.com</code>

**Also**, you must subscribe this address to the [[http://mail.xfce.org/mailman/listinfo/xfce4-commits|xfce4-commits]] mailing list.  If you don't wish to receive mail from this list, you can disable mail delivery.  If you do not subscribe, commit notifications will not go to the list.  We're working on a way to remove this requirement, but for now you will need to be subscribed. At the moment, committing with an @xfce.org email doesn't put that requirement thus you can run the command above without the ''%%--global%%'' option in your individual Xfce projects.

If you have a ssh account, you can clone a repository with:

<code>git clone ssh://git@git.xfce.org/$TYPE/$MODULE</code>

This will automatically set up the 'origin' remote in the cloned repository to point to that location, so a "git push" will do the right thing. You can also clone through a regular ''git:'' url and add the following snippet to ''.git/config'' :
<code>
[url "ssh://git@git.xfce.org"]
        pushInsteadOf = "git://git.xfce.org"
</code>

Unfortunately, we cannot support https pushes at this time due to limitations in the Git http protocol support.  If you are unable to communicate with git.xfce.org on port 22, ''git push'' will not work for you.

===== Translator Access =====

Translators should use [[https://translations.xfce.org/|our Transifex install]] to submit translation updates.  Direct access to the git repository is no longer provided.

If you do not have an account, register for one at our Transifex site and inquire on [[xfce-i18n@xfce.org]] about commit access.  See our [[:translations]] page for more information.

===== Account Maintenance =====

To change your password and manage your active ssh keys, you should login to the [[https://releases.xfce.org/|release manager]] and go to the profile page.

===== New Repositories =====

For 'Goodies' developers, we used to have an "open repository creation" policy in our Subversion repo in which any user with write access could create a new module for a new project.  With the move to Git, this is no longer possible.  You will need to request the creation of a new Git repo by emailing [[xfce-repo-admin@xfce.org]] to request a new module.  Please include your git.xfce.org ssh username, the module name, which category it should be under (apps, art, bindings, libs, panel-plugins, or thunar-plugins), a description of the module, and a rationale as to why it should be hosted on git.xfce.org (instead of github, gitorious, etc.).  Note that requests to be added to the 'admin,' 'archive,' or 'xfce' categories will be denied.

===== Policies =====

  - Modification of tags is not allowed after they have been pushed to the main repository.
  - Pushing "lightweight" non-annotated tags is not permitted.
  - Pushes that result in a non-fast forward update for 'master' branches, and 'xfce-4.x' branches are not allowed.

===== Repository Identification =====

In order to display repository metadata on the [[http://git.xfce.org|CGit]] listings and other places, modules will need a file called "''module.xml''" in the root of their tree (on their master branch).  This file should be a [[http://trac.usefulinc.com/doap|DOAP]] file describing the project.  You can work off [[http://mocha.xfce.org/~kelnos/module-template.xml|this template]].

Please at least provide ''<foaf:name>'', ''<foaf:mbox>'', and ''<gnome:userid>'' elements (the latter of which should be your Xfce ssh account username).  You can of course provide more information about yourself if you'd like; see [[http://xmlns.com/foaf/spec/20071002.html#term_Person|foaf:Person]] and [[http://xmlns.com/foaf/spec/20071002.html#term_Agent|foaf:Agent]].

For now, only include one ''<maintainer>'' element block.  If there are other active developers (or former developers you wish to credit), use a ''<developer>'' element block for each one.

Note that the file in your git repository should actually be named "''module.xml''".  Do NOT replace "''module''" with the actual name of your module.

Changes will not show up immediately; the listings are only regenerated twice daily.

===== Commit Notifications =====

We are doing away with the goodies-commits email list.  All commit mails in all git repositories will go to the [[http://mail.xfce.org/mailman/listinfo/xfce4-commits|xfce4-commits list]].  The subject lines of the emails should be pretty easy to filter on if you only want a subset of emails.  We generate one commit mail per commit object (and for some other things too), so if you push a large number of commits, you'll generate a large number of emails.

===== Tips and Tricks =====

See [[dev:howto:git-tips-and-tricks]].

===== Migrating From git-svn Clones =====

This section is only useful for developers who were using git-svn to access our old Subversion repositories.

If you have a git-svn clone and there are commits in it that you never pushed to svn, and want to merge them into a new git clone, it can be a little bit of a pain.  Because of how the repositories were converted, the git-svn clones do not have the same SHA1 sums for any old commits (that is, commits that were pushed to the svn repo).  So you can't just import a branch directly and expect it to work.

The following is what I (Brian) did.  It's really manual and annoying.  If anyone has a better way, feel free to edit this and describe your method.

Here I'll use my ''xfdesktop'' repo as an example.  I'll refer to the new git clone simply as ''xfdesktop'', and the git-svn clone as ''xfdesktop.git-svn''.  I want to merge the branch ''new-drawing'' from ''xfdesktop.git-svn'' over to ''xfdesktop''.  Here's what I'd do:

<code>$ cd xfdesktop
$ git checkout master
$ git checkout -b new-drawing
$ git fetch ../xfdesktop.git-svn new-drawing:refs/heads/tmpbranch
$ git log tmpbranch</code>

At this point, I'll look at the log output and figure out which commits were never pushed to the main Subversion repository.  It's easy to tell because those commits don't have ''git-svn-id:'' lines at the end of each commit message.

Now, I make a list of the SHA1 hashes of the commits I need to migrate.  I'll order them in the **reverse** order, so that the first commit to migrate will be the oldest out of my list.  In my case, I only have two commits, so my list (after reordering) looks like this:

<code>d1e0179e8b6f00e4f452513c100f674f7d35dc11
e3633d52774bd9a2a20ef9af37d3f72f964a2f54</code>

At this point I could make a script to cherry pick them all in order, but since I only have two I'll just do it manually:

<code>$ git cherry-pick d1e0179e8b6f00e4f452513c100f674f7d35dc11
$ git cherry-pick e3633d52774bd9a2a20ef9af37d3f72f964a2f54</code>

(Note: if there's only one commit to merge, you can skip the above and just do ''git cherry-pick tmpbranch'', which will just cherry pick the ''HEAD'' commit of ''tmpbranch''.)

Now, if I got any merge errors after one of the cherry pick commands, I'd have to stop there and fix it up first:

<code>$ vim src/xfdesktop-icon-view.c
[fix the merge conflict and save]
$ git add src/xfdesktop-icon-view.c</code>

The merge conflict error message provided a useful bit of info: after fixing the conflicts, you can easily re-commit using the same log message, author, and author date as before by using the ''-c'' option to ''git commit'':

<code>$ git commit -c e3633d52</code>

Note that the argument to ''-c'' is just a shortened form of the SHA1 hash for the commit that caused conflicts.

Now that we're done, we can delete the temporary branch:

<code>$ git branch -D tmpbranch</code>

You'll have to repeat this process for any other local branch you have in the old git-svn clone.  As I said, yes, it's annoying, repetitive, manual, and time-consuming (if you have a lot of branches/clones to convert).  If anyone knows a better way, feel free to detail it here.

After you finish with all branches in a particular module, you may want to run:

<code>$ git gc --prune=now</code>

This will remove all the dangling commits, trees, and blobs left over from the probably-large number of mismatched objects discarded when you deleted tmpbranch.