m (added lineending issue under msysgit) |
m (→git on Windows) |
||
| Line 133: | Line 133: | ||
=== git on Windows === | === git on Windows === | ||
When using git on Windows you might use [http://code.google.com/p/msysgit/ msysgit]. If you notice, that all files seem to have changed after doing a fresh clone, this discussion should help you: [http://code.google.com/p/msysgit/issues/detail?id=83]. Find your global git configuration file, normally somewhere under c:\programs\git\etc\gitconfig, and set the parameter ''autocrlf'' in the ''core'' section to ''false''. | When using git on Windows you might use [http://code.google.com/p/msysgit/ msysgit]. If you notice, that all files seem to have changed after doing a fresh clone, this discussion should help you: [http://code.google.com/p/msysgit/issues/detail?id=83]. Find your global git configuration file, normally somewhere under c:\programs\git\etc\gitconfig, and set the parameter ''autocrlf'' in the ''core'' section to ''false''. Then remove you last clone and do a nwe fresh clone. | ||
Revision as of 08:59, 17 November 2008
This page provides some information about our switch to git (which, as of Nov 14th, has been completed). As an initial comforting note, git really isn't so complicated as some people would have you believe. A few months ago I became familiar with distributed version control by using Mercurial, and since a few weeks we're using git at work. I think we'll benefit a lot from switching to it on the long run.
The primary repository
Initial setup
With Git, we'll have one repository for each project. The central repositories through which we cooperate are hosted on gitorious.org. Gitorious is a friendly website that is also open source. On Gitorious the main repository for each project is called mainline. Once you click to the mainline repository, you can see several ways to clone it (the new svn checkout).
We've categorized all projects related to The Mana World, so you can easily see the complete list of The Mana World projects on Gitorious. The projects have different clone URLs for read-only or developer access. The URL for developer access is called the "push URL", since it allows you to push commits into the repository via ssh. The list below is for your convenience.
| Project | Read-only URL | Push URL | Atom feed |
|---|---|---|---|
| TMW client | git://gitorious.org/tmw/mainline.git | git@gitorious.org:tmw/mainline.git | Atom |
| TMW client data | git://gitorious.org/tmwdata/mainline.git | git@gitorious.org:tmwdata/mainline.git | Atom |
| TMW server | git://gitorious.org/tmwserv/mainline.git | git@gitorious.org:tmwserv/mainline.git | Atom |
| TMW web frontend | git://gitorious.org/tmwweb/mainline.git | git@gitorious.org:tmwweb/mainline.git | Atom |
| TMW website | git://gitorious.org/tmw-website/mainline.git | git@gitorious.org:tmw-website/mainline.git | Atom |
| eAthena server | git://gitorious.org/tmw-eathena/mainline.git | git@gitorious.org:tmw-eathena/mainline.git | Atom |
| eAthena data | git://gitorious.org/tmw-eathena-data/mainline.git | git@gitorious.org:tmw-eathena-data/mainline.git | Atom |
Git uses ssh's private/public key authentication for identifying committers. For development purposes you should clone the "push url", but this requires that you have:
- Signed up to gitorious.org
- Generated a private/public ssh keypair (if you haven't got this already)
- Filled in your public key in your account details on Gitorious
Cloning
If you simply git clone the URL without any additional arguments, it will create the repository in a directory called "mainline". This is generally not what you want. Hence, after the clone url, you should pass the name of the directory you want to have created (just like with Subversion):
$ git clone <clone_url> project
If you want to have all projects in one place, you probably want to do something like this:
$ mkdir tmw $ cd tmw $ git clone git@gitorious.org:tmwserv/mainline.git tmwserv $ git clone git@gitorious.org:tmw-eathena-data/mainline.git eathena-data etc. or for all of them in one go (after the cd tmw step): $ for repo in tmw tmwdata tmwserv tmwweb tmw-website tmw-eathena tmw-eathena-data ; do git clone git://gitorious.org/${repo}/mainline.git $repo ; done
The way Gitorious works, we can't have one top-level "tmw" project under which we put all these repositories, since they're really separate projects. Gitorious allows multiple repositories for each project, but they are clones of each other (you can only create new ones by cloning existing ones). This allows anybody (not just the development team) to make clones and start hacking on them. Changes can easily be merged from one one repository to another. So instead of all the inconvenience with TMW forks we had in the past, now comes the time to encourage people to clone!
The TMW 0.0.x client
The 0.0 client may seem a bit hidden, but it exists as a branch just like with Subversion. To continue working on this client you need to checkout the branch and create your own local branch to work on it. This goes as follows:
$ git clone git@gitorious.org:tmw/mainline.git tmw $ cd tmw $ git checkout -b 0.0 origin/0.0
With the last command, a new local branch called 0.0 is created. Since it was based on the 0.0 branch in origin (the repository on Gitorious), it will automatically track this remote branch. This means that when you do git pull, git will attempt to automatically merge the latest changes available from this branch with your local 0.0 branch.
Working with git
Commit
From now on, a commit is something you do locally. Others won't see your change on Gitorious unless you push it there. You'll notice committing is very fast, and you can commit multiple times before you decide to push. You can also make corrections to your last commit.
Before you start committing, it is important to identify yourself to git, so that it can include the correct authorship information with your commit. You are no longer identified with a username, as was the case with Subversion. You can read exactly how to do this, as well as other useful information geared towards people switching from Subversion, on this page:
- Git - SVN Crash Course: http://git.or.cz/course/svn.html
Pushing
Once you have committed some stuff, you can push these to the repository on Gitorious using git push. This works since by default the push command pushes to a remote called origin, and this remote is automatically set up when you clone. However, the push will fail if there have been new commits on the remote repository. In that case, you'll first have to pull in these changes (just like with Subversion, however Subversion allowed this as long as the same files weren't touched, git doesn't).
Pulling
When you want to get the latest changes from the repository on Gitorious, you generally use git pull. However, note that this command does not work when you have local changes. Also, when you have local commits, the pull command will generate a merge commit (and before that you may have to resolve some conflicts).
If you don't want to create merge commits, but would rather stack your local commits on top of any incoming commits, you should use git pull --rebase. This rebases your local commits on top of the incoming ones. You should never do this when you have pushed these commits elsewhere, so only do it when you are sure the commits are only on your machine.
If you have local changes and want to update your checkout, then there are several options:
- You commit your local changes, and do a pull, optionally with --rebase.
- Or you use
git stashto place your local changes on a "hidden" stash. Then, after pulling, you apply your changes again withgit stash apply. - Or you create a patch of your local changes that you apply again after the pull. This approach sometimes makes sense, but I would say in general it's the more clumsy way to go. There are git commands that help you with this though.
Resolving conflicts
Rather similar to Subversion. When there are conflicts, a merge or a rebase will add conflict markers into files. Use git status to see which files remain in conflict and use git add on files to mark them as resolved. When you did a merge and you have resolved all conflicts, you commit. When you were doing a rebase of several commits, you do git rebase --continue instead.
Good to know
Git has several useful commands to figure out the current state of your repository, your files and what recently changed. Below is a non-exhaustive list of commands that are useful to know:
- git branch: Without any parameters, this command should you your local branches, and indicates which branch you're currently on.
- git whatchanged: This shows something similar to the ChangeLog file. Recent commits on your current branch with a list of the files the touched.
- git status: This shows all kind of things about your current checkout: which files changed, untracked (unknown) files, added or removed files, files that have conflicts (during merge), etc. It also shows the status of your index, which is what git will commit once you do
git commit. If you're new to git I would recommend to wait a bit with learning how to use the index, but not to avoid it forever.
There are also additional applications that help you with using git:
- gitk: A simple but effective tool that visualizes the history and some of your current state. Run with
--allto have it show all branches, otherwise it will just show stuff relevant to your current branch. - tig: A textual interface, rather similar to an email reader.
- git gui: A gui tool like gitk which helps you prepare and perform your commits. Also makes it easier to understand the index concept.
git on Windows
When using git on Windows you might use msysgit. If you notice, that all files seem to have changed after doing a fresh clone, this discussion should help you: [1]. Find your global git configuration file, normally somewhere under c:\programs\git\etc\gitconfig, and set the parameter autocrlf in the core section to false. Then remove you last clone and do a nwe fresh clone.
