Familiar with git and just want to know about the git mirror of the OHRRPGCE svn repository? Skip to #The OHRRPGCE git-svn mirror
- 1 Introduction to git
- 2 The OHRRPGCE git-svn mirror
- 3 OHRRPGCE-specific git configuration
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.
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)
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)
After installing git, go to a terminal/command prompt, and type the following command:
git clone https://email@example.com/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
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
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
To learn more ways to use git, type:
or read the git FAQ at http://git.or.cz/gitwiki/GitFaq
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.
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://firstname.lastname@example.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).
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.
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
- 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.)
- 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 :)