Git

Familiar with git and just want to know about the git mirror of the OHRRPGCE svn repository? Skip to #The OHRRPGCE git-svn mirror

Introduction to git

What is git?

git is a distributed version control system. Like subversion, it provides a way to store a complete history of changes to a set of files, and also provides the ability to create "patches" and merge changes from different people. Unlike subversion, 99% of development can be done without any need for internet connectivity, you can maintain your own local history and branches, it is much more secure, orders of magnitude faster, and it fully supports binary files.

If you want to learn more about git, visit http://git-scm.org/ (check out the free git ebook, too -- it's an excellent introduction). This page will focus on the simplest usage of git, which is using it to get the latest version of the OHRRPGCE.

Graphical git

While git's extremely powerful commandline interface is not replicable by any reasonable GUI, programs such as git-cola and giggle provide effective interfaces for most common tasks (committing and reviewing commits and revision history).

In Linux, these tools may be available from your package manager. In Windows, these may be available ??? (please revise this if you know more about windows git GUIs).

gitk (and git-gui) is distributed as part of git, and is an excellent tool for viewing the commit history. Just run "gitk" from the commandline.

Command Line Git (for Hackers)

Getting it

The latest version of git can be downloaded from http://git-scm.com/download Binary packages for Windows, Red Hat, Debian, and OS X are available there, as well as source packages. Your Linux distribution is likely to have a git package available too, if you run Linux :)

All instructions following are for Windows systems, and can trivially be translated to linux (eg. replacing c:\ohrrpgce with ~/ohrrpgce

Using it

After installing git, go to a terminal (command prompt), and type the following command:

git clone https://rbv@bitbucket.org/rbv/ohrrpgce-svn.git --origin svn c:\ohrrpgce

You can check out the source code into any directory you want, c:\ohrrpgce is just a suggestion.

If on Windows, you'll probably want to turn off automatic line ending translation; this seems to interact badly with the svn bridge and cause git to report some pristine files as modified:

cd c:\ohrrpgce
git config core.autocrlf false

Updating

After you have checked out a copy of the source code, you can update it any time by going to a DOS prompt and typing:

cd c:\ohrrpgce
git pull --rebase

(this is vastly faster than the initial clone operation, since only changes are transferred.)

It is also possible to update direct from ohrrpgce SVN. However, please don't do this yet:

cd c:\ohrrpgce
git svn rebase

Making a patchset

If you want to create a patch (instead of just using a pull request) you can use

git format-patch BASECOMMIT

where BASECOMMIT is the commit that you want to calculate differences relative to.

This creates a series of patches in the current directory named like

0001-Preliminary-work-on-drawing-text-boxes-with-slices.patch

As to getting a patchset applied to HEAD, it is too early to comment on that.

Knowing what you have changed

If you have lost track of what files you have changed, you can get a quick list by typing

cd c:\ohrrpgce
git status

You can also get a list of changes in detail (diff format) by:

cd c:\ohrrpgce
git diff

although you may prefer to use a GUI for reviewing such changes. On Linux, setting diff colorization to 'always' and piping 'git diff' output through 'less -r' works pretty well -- NeoTA

Learning more

To learn more ways to use git, type:

git help

or read the git FAQ at http://git.or.cz/gitwiki/GitFaq

There are several other resources at http://git-scm.com/documentation; there is also a book (readable online) at http://progit.org/ , which is pretty comprehensive.

You can use git in all the usual ways. If you want to merge changes to the svn repository through 'git svn dcommit', there are certain limitations to bear in mind -- for example, SVN's notion of branching is so crude that, while it's fine to make local branches using the standard 'git branch' command, any changes that you want to merge with SVN head should be merged into the local 'master' branch before dcommitting.

see http://progit.org/book/ch8-1.html

Using 'git svn dcommit' to push changes upstream also probably requires some changes to local git configuration (ie. so svn recognizes your authorization to commit changes). Hopefully more information on this can be placed here when we know more.

The OHRRPGCE git-svn mirror

Get the git mirror of the subversion repository here (updated every 20 minutes):

  git clone https://rbv@bitbucket.org/rbv/ohrrpgce-svn.git --origin svn

Setting the remote name to "svn" is optional, but allows using git svn directly in the future if you wish (see below).

Browsing

If you just want to browse the repository without actually checking it out, you can go to https://bitbucket.org/rbv/ohrrpgce-svn/src

Branches

This git-svn bridge includes various branches:

• wip: The main development branch; the next version of the OHR. This is an extended version of the history of wip/ in the SVN repository (see below).
• callipygous, beelzebufo, etc release branches
• tools: Contains Hamster Whisper and rpgbatch. This is not connected to the wip branch, so you might like to check it out separately in another repository using "git clone /path/to/ohrrpgce-svn ohrrpgce-tools".
• web: Various HamsterRepublic.com web and cron scripts. This is not connected to the wip branch. Of little interest to most people.
• fbohr: An import of the obsolete and no longer available FBOHR SVN repository. This is not connected to the wip branch, but a copy of the fbohr history is spliced into wip.
• old-linear: This is a copy of the first 425 svn commits (plus a copy of the source from 2000) without the fbohr commits spliced into the history. (See below.)

The games/ directory in the svn repository (James' OHRRGPCE games) is not included.

Spliced history

The git history contains a few extras not in the svn repository. Firstly there are two commits before the start of svn history, showing the state of the source code in 2000. Secondly, the FBOHR history has been manually spliced into the ohrrpgce history by giving some commits extra parents to turn them into merges (this was accomplished with git grafts and then made permanent), to try to make sense of some of the huge patches Simon introduced. These aren't like normal git merges, since often only a subset of files were copied from one repo to the other, but the merge diffs look normal since files not copied across are ignored.

If you don't like having a non-linear git history which differs from the "real" svn history, you can easily get rid of the fbohr history by doing:

 git replace 7a5720da6b1d7585cf1413c7bc8d0b56c62ac6e8 $(git rev-parse svn/old-linear)

(This still has the commits from 2000 grafted in front.) This "git replace" command is totally safe; it does not change the hashes for any commits after r425, and will not even be visible when you push stuff elsewhere (unless you intentionally push ref/replaces/*).

Other git repos

• https://bitbucket.org/rbv/ohrrpgce-svn/overview

This is TMC's repository, where you will find an excessive number of branches for features he is working on. (Many of these branches are branched off an incompatible git-svn import of the svn history, and need rebasing onto the new one.)

Using git-svn yourself

If you want, you can use git svn to read and write directly to the svn repository. SHA1 hashes for git history should stay the same as the one in the ohrrpgce-svn mirror, unless somebody edits an svn commit (use git svn reset to recover from that, or just delete .git/svn).

   git config svn-remote.svn.url https://rpg.hamsterrepublic.com/source
   git config svn-remote.svn.fetch "wip:refs/remotes/svn/wip"
   git config svn-remote.svn.fetch "tools:refs/remotes/svn/tools" --add
   git config svn-remote.svn.fetch "web:refs/remotes/svn/web" --add
   git config svn-remote.svn.branches "rel/*:refs/remotes/svn/*"

Don't try to use any git svn commands before performing the above setup. These config lines are the equivalent of "git svn init" (which doesn't have flexible enough commandline options).

Then, run

   git svn fetch --log-window-size=10000

This will fetch the log from the svn server and then build the rev-maps (svn revision number to git sha1 mapping) under .git/svn, and will take a minute or two. Don't try to fetch all the commits from svn instead of the provided ohrrpgce-svn repo!

Great, now you are ready to use git svn rebase to fetch svn commits and rebase your local branch on top (or just use git svn fetch), and git svn dcommit to push commits from your local branch to svn.

How this works is that git svn and git fetch both put branches into the refs/remotes/svn/ directory which are completely identical. If you pull some more commits from the ohrrpgce-svn mirror with git fetch svn then git-svn will update its rev-maps to include them when it's next run. If you import commits from svn yourself with git svn fetch then you will create new commits identical to the ones which will also be added to the ohrrrpgce-svn repo.

http://progit.org/book/ch8-1.html covers the subject of svn / git interoperation well.

OHRRPGCE-specific git configuration

It's hugely helpful to set up rules for printing diffs of FreeBASIC and RELOAD documents. Add the following to .git/config

[diff "basic"]
	xfuncname = "^((PRIVATE|private|Private|PUBLIC|public|Public)? *(SUB|sub|Sub|FUNCTION|function|Function|TYPE|type|Type|ENUM|enum|Enum|UNION|union|Union).*)$"
[diff "hamsterspeak"]
	xfuncname = "^((script|plotscript|define ?constant|global ?variable|define ?function|define ?script|define ?operator|define ?trigger).*)$"
[diff "reload"]
	textconv = reload2xml
        cachetextconv = true

(Change 'reload2xml' to 'reload2xml.exe' on Windows, and make sure that you've built it and the binary is in your PATH.)

And the following to .git/info/attributes

*.reld  diff=reload
*.slice diff=reload
*.editor  diff=reload
*.bas   diff=basic
*.rbas  diff=basic
*.bi    diff=basic
*.hss   diff=hamsterspeak
*.hsi   diff=hamsterspeak
*.hsd   diff=hamsterspeak

A great project would be a utility to print diffs for rpg files and .rpgdir folders using nohrio :)