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 is definitely available in Windows.

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 DOS prompt, and type the following command:

git clone git://gitorious.org/ohrrpgce-svn/ohrrpgce-svn.git c:\ohrrpgce

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

You now have the entire project history available to you. Be aware that this includes only ohrrpgce WIP, not the games directory or other modules. This may change in the future, according to demand.

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

you can make a patchset using

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

OHRRPGCE-specific git configuration

Lots of files are produced when compiling and running the OHRRPGCE, so you'll want to set some rules for ignoring files when printing 'git status'. An example file is User:The Mad Cacti/.gitignore, name this either .gitignore file in the working directory, or .git/info/exclude.

Also, 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

(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
*.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 :)

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.

Understanding the git-svn bridging

Unless you have commit permission, you probably do not need to know this.

The git repository was cloned from the subversion repository with the command 'git svn clone svn://gilgamesh.HamsterRepublic.com/ohrrpgce/wip'. This is slow and bandwidth-intensive, do not do it unless you really truly must..

You should usually avoid using 'git svn fetch', as because svn only supports a linear development history, it doesn't cope well with true branches (which can come into existence if you checkout ohrrpgce, make some changes, and then fetch the latest version (which happens to have conflicting changes; there are now two branches, the 'canonical' one and your local one)). While git svn fetch can be a useful merge tool, usually what you really want is 'git svn rebase'

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

http://gitorious.org/ohrrpgce-svn/pages/Home provides some links to help svn users to understand git.

Browsing

If you just want to browse the repository without actually checking it out, you can use http://gitorious.org/ohrrpgce-svn/ohrrpgce-svn/trees/master