From The Mana World
(→‎Initial setup: Changed some tmwAthena data repos from gitorious to github)
(remove outdated branding link)
(23 intermediate revisions by 8 users not shown)
Line 1: Line 1:
We are using the version control system Git as our main collaboration tool. You can use it to obtain all the sourcecode and content files you need to take part in the development or to create your own fork. See [http://en.wikipedia.org/wiki/Git_(software) the wikipedia article about Git] and [http://git-scm.com/ the Git homepage] for details about Git.
 
==Git==
 
'''git''' is the name of the program intended to allow a team to work on a set of program sources, keep versions synchrone and make members team work easily known from others.
[https://gitorious.org/about Gitorious] and [https://github.com/ github] are websites that provide free hosting of public git repositories.
At some point we moved the content repositories from gitorious to github and later to gitlab. See this forum topic [http://forums.themanaworld.org/viewtopic.php?p=121526#p121526] for reference. (Note server code was transferred to github since it was written)
We are using the version control system Git as our main collaboration tool. You can use it to obtain all the sourcecode and content files you need to participate in the development or to create your own fork.  
 
See [http://en.wikipedia.org/wiki/Git_(software) the wikipedia article about Git] and [http://git-scm.com/ the Git homepage] for details about Git.
 
In TMW wiki, information about Git  is still located in several places where you may find contradictory information. We do apologize for that and work hard to let you have a clear information:
* '''This page''': The actual links to various repositories should be up to date but some information about how to work with it is not.It still contains useful information and GUI's information should be correct.
* '''[[How to Develop]]''' also duplicates some info which you can find else where. It will be completely re-written  to make it the entry point of the  wiki development part.
* '''[[Working With Git]]''' contains the most up to date information to use Git with the command line. ''It is the actual reference that you should follow''. It is important to read it even if you plan to use a graphical user interface.


== The primary repository ==
== The primary repository ==
Line 6: Line 19:




With Git, we'll have one repository for each project. The central repositories through which we cooperate are hosted on [http://gitorious.org/ 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 <code>svn checkout</code>).
With Git, we'll have one repository for each project. The central repositories through which we cooperate are hosted on '''[https://github.com/ github.com]'''. '''github''' is a friendly website. On '''github''' the main repository for each project is called ''master''. Once you click to the master repository, you can see several ways to clone it (the new <code>svn checkout</code>).


We've categorized all projects related to The Mana World, so you can easily see the complete [http://gitorious.org/search?q=category%3Athe-mana-world 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.
We've categorized all projects related to The Mana World, so you can easily see the complete [https://github.com/themanaworld list of The Mana World projects] on '''github'''. The projects have different forks (clone) URLs for browsing, 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.
 
 
'''Very outdated! see [[How to Develop]] for more current repositories'''


{|border="1" cellspacing="0" cellpadding="5"
{|border="1" cellspacing="0" cellpadding="5"
! Project
! Project
! Read-only URL
! Read-only URL
! Push URL (Developers only)
! Atom feed
! Atom feed
|-
|-
| '''[http://gitorious.org/tmw/tmw Mana branding]'''
|colspan=4| <span style="color:White; background:Sienna">TMW, TMW eAthena</span>
| git://gitorious.org/tmw/tmw.git
| git@gitorious.org:tmw/tmw.git
| [http://gitorious.org/tmw/tmw.atom Atom]
|-
|-
|colspan=4|This repository contains the branding files to turn Mana into TMW.
|colspan=4|This repository contains the branding files to turn Mana into TMW.
|-
|-
| '''[https://github.com/themanaworld/tmwa-client-data TMW tmwAthena client data]'''
| '''[https://github.com/themanaworld/tmwa.git eAthena server]'''
| git://github.com/themanaworld/tmwa-client-data.git
| git://github.com/themanaworld/tmwa.git
| push access on request
| [https://github.com/themanaworld/tmwa/commits/master.atom Atom]
| [https://gitorious.org/tmw/tmwa-client-data.atom Atom]
|-
|-
|colspan=4|This repository has the client data for TMW's tmwAthena.
|colspan=4|This repository contains our hacked up eAthena.
|-
|-
| '''[https://github.com/themanaworld/tmw-music TMW music]'''
| '''[https://github.com/themanaworld/tmwa-server-data tmwAthena Server data]'''
| git://github.com/themanaworld/tmw-music.git
| git://github.com/themanaworld/tmwa-server-data.git
| push access on request
| [https://github.com/themanaworld/tmwa-server-data/commits/master.atom Atom]
| [http://gitorious.org/tmw/music/commits/master/feed.atom Atom]
|-
|-
|colspan=4|This repository has the background music for the client.
|colspan=4|This repository contains the server data developed for the tmwAthena server and used by The Mana World.  
|-
|-
| '''[http://gitorious.org/tmw/client-data TMW client data]'''
| '''[https://github.com/themanaworld/tmwa-client-data TMW tmwAthena client data]'''
| git://gitorious.org/tmw/client-data.git
| git://github.com/themanaworld/tmwa-client-data.git
| git@gitorious.org:tmw/client-data.git
| [https://github.com/themanaworld/tmwa-client-data/commits/master.atom Atom]
| [https://gitorious.org/tmw/client-data.atom Atom]
|-
|-
|colspan=4|This repository contains the client data for TMW's ManaServ.
|colspan=4|This repository contains the data used by The Mana World clients for the tmwAthena server. .
|-
|-
| '''[https://github.com/themanaworld/tmwa-server-data/ TMW server data]'''
| '''[https://github.com/themanaworld/tmw-art TMW Art]'''
| git://github.com/themanaworld/tmwa-server-data.git
| git://github.com/themanaworld/tmw-art.git
| push access on request
| [https://github.com/themanaworld/tmw-art/commits/master.atom Atom]
| [https://gitorious.org/tmw/server-data.atom Atom]
|-
|-
|colspan=4|This repository contains the server data for TMW's ManaServ.
|colspan=4|This repository contains some sources for our artwork.
|-
|-
| '''[http://gitorious.org/tmw/website TMW website]'''
| '''[https://github.com/themanaworld/tmw-music TMW music]'''
| git://gitorious.org/tmw/website.git
| git://github.com/themanaworld/tmw-music.git
| git@gitorious.org:tmw/website.git
| [https://github.com/themanaworld/tmw-music/commits/master.atom Atom]
| [http://gitorious.org/tmw/website/commits/master/feed.atom Atom]
|-
|-
|colspan=4|This repository has our website.
|colspan=4|This repository contains the music used by The Mana World clients for the tmwAthena server.  
|-
|-
| '''[http://gitorious.org/tmw-eathena eAthena server]'''
| '''[https://github.com/themanaworld/themanaworld-website TMW website]'''
| git://gitorious.org/tmw-eathena/mainline.git
| git://github.com/themanaworld/themanaworld-website.git
| git@gitorious.org:tmw-eathena/mainline.git
| [https://github.com/themanaworld/themanaworld-website/commits/master.atom Atom]
| [http://gitorious.org/tmw-eathena/mainline/commits/master/feed.atom Atom]
|-
|colspan=4|This repository contains our hacked up eAthena.
|-
|-
| '''[http://gitorious.org/tmw/tmwa-server-data tmwAthena data]'''
|colspan=4|This repository contains the website of The Mana World.  
| git://gitorious.org/tmw/tmwa-server-data.git
| git@gitorious.org:tmw/tmwa-server-data.git
| [https://gitorious.org/tmw/tmwa-server-data.atom Atom]
|-
|-
|colspan=4|This repository has the data for our tmwAthena.
|colspan=4|<span style="color:White; background:Sienna">Official client: ManaPlus.</span>
|-
|-
| '''[http://gitorious.org/tmwart TMW Art]'''
| '''[https://gitorious.org/manaplus/manaplus/ ManaPlus client]'''
| git://gitorious.org/tmwart/mainline.git
| https://gitlab.com/manaplus/manaplus.git  
| git@gitorious.org:tmwart/mainline.git
| [https://gitlab.com/manaplus/manaplus.atom Atom]
| [http://gitorious.org/tmwart/mainline/commits/master/feed.atom Atom]
|-
|-
|colspan=4|This repository has some sources for our artwork.
|colspan=4|This repository contains the ManaPlus client sources.
|}
|}


For the Mana (the client) and Manaserv, look at http://doc.manasource.org/git_repository.
For the Mana (the client) and Manaserv, look at http://doc.manasource.org/git_repository.


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:
Git uses ssh's private/public key authentication for identifying committers. For development purposes just clone the read-only URL, it will automatically switch to the push URL if you have:


# Signed up to gitorious.org
# Signed up to github.com
# Generated a private/public ssh keypair (if you haven't got this already)
# Generated a private/public ssh keypair (if you haven't got this already)
# Filled in your public key in your account details on Gitorious
# Filled in your public key in your account details on GitHub
 
# Been added with commit rights to the repository
=== Cloning ===
# Followed the directions in the [How to Develop] page
 
If you simply <code>git clone</code> 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:tmw/mainline.git tmw
$ 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 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!
 
==== Shallow cloning for non-developers ====
 
One of our repositories, tmwdata, has grown quite large cause of its long history filled with relatively large binary files. If you are only interested in getting the latest version, and have no need to be able to push back changes, then you can make a shallow clone:
 
$ git clone --depth 1 git://gitorious.org/tmwdata/mainline.git tmwdata


== Working with git ==
== Working with git ==
All TMW specific repositories have been now moved to github:[https://github.com/themanaworld https://github.com/themanaworld]


=== Commit ===
:::'''[[Working With Git]]'''
 
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
 
Sample commit message:
  This is the title. Keep this line short.
 
  This is a longer description of the commit, if needed. Keep these
  lines short too. A sample list:
  <nowiki>* Item 1</nowiki>
  <nowiki>* Item 2</nowiki>
  <nowiki>* Item 3</nowiki>
 
  Another paragraph in the commit description. Blah blah blah.
 
=== Pushing ===
 
Once you have committed some stuff, you can push these to the repository on Gitorious using <code>git push</code>. 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 <code>git pull</code>. 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 <code>git pull --rebase</code>. 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 <code>git stash</code> to place your local changes on a "hidden" stash. Then, after pulling, you apply your changes again with <code>git stash apply</code>.
* 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 <code>git status</code> to see which files remain in conflict and use <code>git add</code> 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 <code>git rebase --continue</code> instead.
 
=== Patch making ===
 
Git has an easy way to send patches to other people to review and commit for you. After you have made a commit, <code>git format-patch</code> will make a patch out of it. The patch includes your author information the commit message you gave, and all the changes to be done. The recipient can just <code>git am [patch file]</code> to apply the commit. After it has been pushed, you'll need to remove the patch from your local repository, <code>git reset --hard HEAD^</code> will do that. If you don't do that, you'll get a conflict when your patch is pulled from the central repository.
 
=== 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 lists your local branches, and indicates which branch you're currently on.
* '''git whatchanged''': This shows a list of all commits on the current branch similar to <code>git log</code>, but with a list of the files that have been touched in each commit as well.
* '''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 <code>git commit</code>. 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:
You may also have a look to the original documentation at [http://git-scm.com/documentation http://git-scm.com/documentation]


* '''gitk''': A simple but effective tool that visualizes the history and some of your current state. Run with <code>--all</code> to have it show all branches, otherwise it will just show stuff relevant to your current branch.
* '''gitk''': A simple but effective tool that visualizes the history and some of your current state. Run with <code>--all</code> to 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.
* '''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 gui''': A gui tool like gitk which helps you prepare and perform your commits. Also makes it easier to understand the index concept.
* '''Giggle'''
* '''qgit'''
* '''git-cola''' : [http://git-cola.github.com/ http://git-cola.github.com/]
* '''SmartGit''' : [http://www.syntevo.com/smartgit/index.html http://www.syntevo.com/smartgit/index.html]'


=== 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 some files seem to have changed after doing a fresh clone, you may want to disable <code>core.autocrlf</code> using <code>git config core.autocrlf false</code>. However, this is not recommended for contributors since the setting makes sure you don't commit Windows style newlines into the repository. When encountering this problem it is usually best to consult other developers about the affected files.
When using git on Windows you might use [http://msysgit.github.com/ msysgit]. If you notice that some files seem to have changed after doing a fresh clone, you may want to disable <code>core.autocrlf</code> using <code>git config core.autocrlf false</code>. However, this is not recommended for contributors since the setting makes sure you don't commit Windows style newlines into the repository. When encountering this problem it is usually best to consult other developers about the affected files.
[[Category:Reference]]
GitHub works uses the same tools as Git.
:'''GUIs'''
* '''GitHub for Windows''' : [http://windows.github.com/ http://windows.github.com/]
* '''Git Extensions''' : [http://code.google.com/p/gitextensions/ http://code.google.com/p/gitextensions/]
* '''git-cola''' : [http://git-cola.github.com/ http://git-cola.github.com/]
* '''SmartGit''' : [http://www.syntevo.com/smartgit/index.html http://www.syntevo.com/smartgit/index.html]
=== git on MacOS X ===
MacOSX is an unix system, BSD derived. Git works there mostly as on Linux systems. Go to the [http://git-scm.com/downloads official download site: http://git-scm.com/downloads] and choose the OS X link, download and install. You also may prefer [http://code.google.com/p/git-osx-installer/ http://code.google.com/p/git-osx-installer/] and add  a graphical user interface later (links are on the same pages). Xcode and X11 are required if you want to install from sources. French users may also like: [https://gist.github.com/656299 https://gist.github.com/656299]
:'''GUIs'''
* '''GitHub for Mac''' github
has it's own application that you can find at [http://mac.github.com/ http://mac.github.com/]. Among others, it has a very nice feature to be able to pull and push in one operation.
* '''GitX''' : [http://gitx.laullon.com/ http://gitx.laullon.com/]
* '''SourceTree''' : [http://www.sourcetreeapp.com/ http://www.sourcetreeapp.com/]
* '''git-cola''' : [http://git-cola.github.com/ http://git-cola.github.com/]
* '''SmartGit''' : [http://www.syntevo.com/smartgit/index.html http://www.syntevo.com/smartgit/index.html]
 
===Glossary===
You may like this very nice interactive memo: '''[http://ndpsoftware.com/git-cheatsheet.html git-cheatsheet]''' by [https://github.com/ndp Andrew Patterson] from NDP software.
 
* Branch
* Clone
* Commit
* Fork
* Mainline
* Master
* Merge
* Origin
* Patch
* Pull
* Push
* Stash
* Tree
 
[[Category:Development]]

Revision as of 01:38, 11 August 2016

Git

git is the name of the program intended to allow a team to work on a set of program sources, keep versions synchrone and make members team work easily known from others. Gitorious and github are websites that provide free hosting of public git repositories. At some point we moved the content repositories from gitorious to github and later to gitlab. See this forum topic [1] for reference. (Note server code was transferred to github since it was written) We are using the version control system Git as our main collaboration tool. You can use it to obtain all the sourcecode and content files you need to participate in the development or to create your own fork.

See the wikipedia article about Git and the Git homepage for details about Git.

In TMW wiki, information about Git is still located in several places where you may find contradictory information. We do apologize for that and work hard to let you have a clear information:

  • This page: The actual links to various repositories should be up to date but some information about how to work with it is not.It still contains useful information and GUI's information should be correct.
  • How to Develop also duplicates some info which you can find else where. It will be completely re-written to make it the entry point of the wiki development part.
  • Working With Git contains the most up to date information to use Git with the command line. It is the actual reference that you should follow. It is important to read it even if you plan to use a graphical user interface.

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 github.com. github is a friendly website. On github the main repository for each project is called master. Once you click to the master 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 github. The projects have different forks (clone) URLs for browsing, 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 Atom feed
TMW, TMW eAthena
This repository contains the branding files to turn Mana into TMW.
eAthena server git://github.com/themanaworld/tmwa.git Atom
This repository contains our hacked up eAthena.
tmwAthena Server data git://github.com/themanaworld/tmwa-server-data.git Atom
This repository contains the server data developed for the tmwAthena server and used by The Mana World.
TMW tmwAthena client data git://github.com/themanaworld/tmwa-client-data.git Atom
This repository contains the data used by The Mana World clients for the tmwAthena server. .
TMW Art git://github.com/themanaworld/tmw-art.git Atom
This repository contains some sources for our artwork.
TMW music git://github.com/themanaworld/tmw-music.git Atom
This repository contains the music used by The Mana World clients for the tmwAthena server.
TMW website git://github.com/themanaworld/themanaworld-website.git Atom
This repository contains the website of The Mana World.
Official client: ManaPlus.
ManaPlus client https://gitlab.com/manaplus/manaplus.git Atom
This repository contains the ManaPlus client sources.

For the Mana (the client) and Manaserv, look at http://doc.manasource.org/git_repository.

Git uses ssh's private/public key authentication for identifying committers. For development purposes just clone the read-only URL, it will automatically switch to the push URL if you have:

  1. Signed up to github.com
  2. Generated a private/public ssh keypair (if you haven't got this already)
  3. Filled in your public key in your account details on GitHub
  4. Been added with commit rights to the repository
  5. Followed the directions in the [How to Develop] page

Working with git

All TMW specific repositories have been now moved to github:https://github.com/themanaworld

Working With Git

You may also have a look to the original documentation at http://git-scm.com/documentation

  • gitk: A simple but effective tool that visualizes the history and some of your current state. Run with --all to 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.
  • Giggle
  • qgit
  • git-cola : http://git-cola.github.com/
  • SmartGit : http://www.syntevo.com/smartgit/index.html'

git on Windows

When using git on Windows you might use msysgit. If you notice that some files seem to have changed after doing a fresh clone, you may want to disable core.autocrlf using git config core.autocrlf false. However, this is not recommended for contributors since the setting makes sure you don't commit Windows style newlines into the repository. When encountering this problem it is usually best to consult other developers about the affected files. GitHub works uses the same tools as Git.

GUIs

git on MacOS X

MacOSX is an unix system, BSD derived. Git works there mostly as on Linux systems. Go to the official download site: http://git-scm.com/downloads and choose the OS X link, download and install. You also may prefer http://code.google.com/p/git-osx-installer/ and add a graphical user interface later (links are on the same pages). Xcode and X11 are required if you want to install from sources. French users may also like: https://gist.github.com/656299

GUIs
  • GitHub for Mac github

has it's own application that you can find at http://mac.github.com/. Among others, it has a very nice feature to be able to pull and push in one operation.

Glossary

You may like this very nice interactive memo: git-cheatsheet by Andrew Patterson from NDP software.

  • Branch
  • Clone
  • Commit
  • Fork
  • Mainline
  • Master
  • Merge
  • Origin
  • Patch
  • Pull
  • Push
  • Stash
  • Tree