[Tutorial] Councilor's friend: Git. (Repository setup. Modding & C++ Engine)

[Radagast.]

The most important step for all our councillors is to

• install git. It's very easy (just an .exe on Windows, the package manager helps on Linux and Mac).
• get known how to use it (either GUI client or command line). --> WINDOWS GUI GUIDE - DETAILED WITH IMAGES.
• Download 0AD GitHub repository in any folder you desire. I recommend CoM/ or com/ (Council of Modders) as we have a share/ repository that doesn't go into the 0AD mods/ folder, too (because it's no mod).
• Download all our mod-packs (aristeia, millenium, generic) into the 0AD mods/ folder. (it's readonly anyway! your files will not be overwritten on 0AD repository update as 0AD has no other mods/ folder than mods/public/.)

If councillors fail in this step, ask for help! Otherwise (without this for all councillors synchronised setup) we have a giant mess (and a timekiller) at hand.

HowTo (*nix systems) & Reasons:

Note: If you wish to work on the C++ engine, SVN is recommended, but if you want to stick to git checkout the CoM Github 0AD fork. Then create a branch for the feature you wish to work on. (create a branch for each separate feature. Keep it as independent as possible. Branch a branch if you have a feature that builds upon another feature.)

Warning: Either make sure the mods/ e.g. mods/aristeia, mods/millenium, .. are excluded and are not going to be committed or check out the 0AD fork trunk a second time to be able to work on the engine and a mod at the same time (without the need to switch).

• cd $HOME    #Change into your home directory or where you want to put the files.

• Start git client to download 0AD trunk repository. OR directly via command line on Linux: (creates a directory 0ad)

  git clone https://github.com/0ad/0ad.git 

• Download the mod in the same manner (via client or command line:)

  mkdir 0ad/binaries/data/mods/aristeia -i && git clone https://github.com/0ADCoM/Aristeia.git 0ad/binaries/data/mods/aristeia

  Download it directly into 0ad/binaries/data/mods/aristeia ! Make sure this directory exists or let the Client create it (or create it like I show in the above command if you are on Linux.

  This way you can easily update the mod from the repository and can directly run 0AD without having to copy or move files. Also you can directly modify the files in there without having to copy things over and over. If you created a branch, you can commit you changes regularly for the case something goes wrong or breaks (so that you can go back).

• Now start the mod like Niek showed for windows. Here for Linux:

  ~/0ad/binaries/system/pyrogenesis -map=aristeia

  In short:

  Have the folder in the /mods folder and link a shortcut to that folder:

  Target: C:\CODE\binaries\system\pyrogenesis.exe -mod=<modfoldername>

  Start in: C:\CODE\binaries\system

  In the example, the -mod=<modfolder> would become -mod=aristeia.

This is how to start the Atlas Editor directly:

~/0ad/binaries/system/pyrogenesis -editor

To visualise our goal: (from nvie.com)

Note:

• master is our fork's always clean base (which we offer to 0AD to pull changes from, alternatively they can pull feature branches individually).
• develop is where we merge all our ready feature branches. This is the one that is recommended for modders to check out separately. In this clean copy we can test our mods. (so engine developers have two local repositories)

The difference between master and develop for us is: master is for 0AD's benefit and for us to have an individual release for testing the overall program.

Moving repositories on your local machine:

Simply copy the entire working directory contents (including the hidden .git directory). This will move the entire working directory to the new directory and will not affect the remote repository on GitHub.

If using GitHub for Windows, it is possible to do this also. After you have moved the working directory trying to access it through the application will produce an error saying the repository cannot be found and will allow for you to select where the working directory now resides.

You have to worry about nothing, as long as the hidden .git is included in the dir it's all fine. Just move the folders whereever you want. Then choose a new location in the complaining GUI.

Edited April 11, 2014 by Hephaestion

[Lion.Kanzen]

May be to reinforces the words I suggest add images in spoiler tags maybe.

[Radagast.]

There are plenty of images in the links. The problem is, there are many operating systems.

The real hurdle just is Git:

• Install. It should integrate into your filesystem. So if you right click on a folder, there are options to commit your files and such. Follow this for Windows. With GUI. So please install it. No problem if our councillors don't like the command line. Yet please install that GUI then. We need Git or we will die from Chaos.
  • I currently collect all our artwork in the share repository.
  • Also I created branches for the engine features that are WIP. (only relevant for C++ developers and testers)
• Then checkout our fork from Github (using the GUI following tutorials from the http://msysgit.github.io site or use command line as I showed above).

  This is the URL you have to enter in the checkout dialog:

  https://github.com/0ADCoM/0ad

  You can find this URL here:

  

• Now checkout our MOD reposiories one by one. Directly into 0ad/binaries/data/mods/ .

That's it. Now you can right click on your folder if you changed something. Then you can send (commit) your changes to the GitHub so that everyone can see it and everybody has the most recent version of all files.

That's it for the modding setup. Pretty easy, no? Ask if it does not work. Or better simply make a Screenshot with the error message and post it. And I will see what I can do. This basic setup every modder of us simply must have. It makes no sense otherwise.

[Lion.Kanzen]

Hmmm we can add icons to replace main 0A.D logo in each of our mods?

[Radagast.]

Now checkout our MOD reposiories one by one. Directly into 0ad/binaries/data/mods/

Note that checkout works always the same way: You look for the Download URL. Then change the directory to where you want the mod* and start the checkout:

git clone <download-url>

or use your GUI.

* This is where we want our mods: 0ad/binaries/data/mods/ <-- note that this way we can always test the most recent version out of the box after checkout! quite handy. It's no problem to have a Git repository within another one (0AD sources). Especially for artists and testers which concentrate on their mod and never commit C++ or JavaScript or art work to the main repository develop.

Hmmm we can add icons to replace main 0A.D logo in each of our mods?

We can change it add. This should be done as late as possible. In the last change before you release your final mod-pack/total conversion.

Edit: Cool. Double-posts are merged automatically ...

Edited April 11, 2014 by Hephaestion