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 command 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. See below.

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

Knowing what you have changed

To see 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 from one of the following places (both updated every 20 minutes... while the cron computer is turned on):

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

These git repositories are identical, but the github one also hosts the official bug tracker.

Setting the remote name to "svn" is optional, but allows using git svn directly in the future if you wish to fetch commits directly from svn, or commit to svn if you have write access (see below).

Browsing

If you just want to browse the repository without actually checking it out, you can go to https://github.com/ohrrpgce/ohrrpgce (secondary mirror: 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/overview

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

• https://github.com/bob-the-hamster/ohrrpgce

This is James's git repository. It rarely has any interesting branches, and it often lags a couple revisions behind subversion, but it should be a convenient place to make pull requests if you have something that you want James to merge.

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 then git fetch svn to recover from that, or just delete .git/svn, see below).

Don't try to use any git svn commands before setting up git-svn by running the following commands. These config command are the equivalent of "git svn init" (which doesn't have flexible enough commandline options). (Note: this will only only work if the ohrrpgce-svn remote is called svn, which is what the above 'git clone' command does. It doesn't matter whether the svn remote points at the github or bitbucket mirror; they're both equivalent and you don't need the other.)

After running git clone you should already have the branches from the ohrrpgce-svn git repo, not just the wip branch (you'll see them listed as remote branches with git branch -a). (If you are missing any branches they will be downloaded slooooooowly from svn, and the hashes won't match.)

   git fetch --all
   # svn/HEAD gets created automatically when cloning, delete it (optional)
   git branch -d -r svn/HEAD 
   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/*"
   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 should also print them to the console), and will take about five minutes or so. (Downloading the log and generating the rev-maps are fast, but there seems to be some bug in git-svn that makes the other step take forever.) Don't try to use a different method to fetch all the commits from svn instead of the provided ohrrpgce-svn repo! The hashes won't match the ohrrpgce-svn repo! If git-svn starts downloading commits one at a time from svn (it'll print lists of changed files), kill it, something went wrong.

If you have any problem while reading/writing svn commits, you can use git svn reset -r ### to make git-svn forget about some recent svn commits (the git commits are not deleted), and then rerun git svn fetch.

If things become totally stuffed up, you can rm -rf .git/svn and then rerun the git svn fetch command. That should just take a few minutes to rebuild the git-svn index.

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 svn (to fetch from the ohrrrpgce-svn git repo) both put branches in 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 the .git/config file:

[diff "basic"]
	xfuncname = "^((PRIVATE|[Pp]rivate|PUBLIC|[Pp]ublic|LOCAL|[Ll]ocal|STATIC|[Ss]tatic)? *(SUB|[Ss]ub|FUNCTION|[Ff]unction|TYPE|[Tt]ype|ENUM|[Ee]num|UNION|[Uu]nion|CONSTRUCTOR|[Cc]onstructor|DESTRUCTOR|[Dd]estructor|OPERATOR|[Oo]perator|PROPERTY|[Pp]roperty|MACRO|[Mm]acro).*)$"
[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 :)