Revision as of 03:05, 7 August 2011

About this Document

This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

It is also not ready for prime-time use. I would consider it alpha quality at this time. -Braids 00:05, 7 August 2011 (UTC)

Install SmartGit

Install command-line Git

SmartGit, a graphical client, requires that regular (command line) Git be installed on your system first.

Install Git for Windows

1. If you use Cygwin, and you have installed Git for that, you supposedly need to uninstall it. Run or download setup.exe from the Cygwin web site to do so. (Braids did not uninstall the Cygwin version, and has had no trouble. This is rather dangerous. Your experience may vary.)
2. Download the latest Git-X.Y.Z-preview executable from the msysgit project. If you are using a version newer than 1.7.6, please comment on this wiki document or post a new topic to the Forge development forum.
3. Run the Git installer executable. A Git Setup window appears.
4. Click Next twice.
5. You may change the destination folder if you want. Either way, click Next.
6. On the Select Components step, Cygwin users will probably want to clear the checkbox next to Associate .sh files to be run with Bash.
7. Additional icons are not necessary, because we intend to use this version of Git as a sort of library for SmartGit. This is left to your discretion.
8. Click Next.
9. Start Menu configuration is left to your discretion.
10. Click Next.
11. Click Run Git from the Windows Command Prompt. SmartGit requires git.exe to be in the PATH.
12. Click Next three times.
13. Click Finish. Close the release notes.

Install Git for MacOS

TODO: Mac specific.

Install and Configure SmartGit

1. Download and install SmartGit for your OS.
2. Launch SmartGit. Setup SmartGit window appears.
3. Read the license. Note that Forge is open source, GPL software, so we can use it for free under the Non-Commercial License clause. (The license is also available in German.)
4. If you agree, place a check next to I understand and agree to all terms and conditions of this agreement. Otherwise, you will have to stop here and find your own Git client.
5. Click Next.
6. Click Non-commercial use only (all features, but no support).
7. Click Next.
8. Browse to your installation's git executable:
   1. For Windows:
      1. Click Choose....
      2. Browse to the folder where you installed Git.
      3. Open the bin folder.
      4. Scroll down and click git.exe in the list on the right.
      5. Click OK.
   2. For MacOS, TODO: Mac specific.
      1. TODO: Step 1 in MacOS.
9. Click Next twice.
10. Enter the User Name you use for Gitorious.
11. Enter the E-Mail you use for Gitorious.
12. Click Next twice. (Gitorious is not in the list of main hosting providers bundled with SmartGit at this time.)
13. Click Finish. The Setup window closes, and the SmartGit and Open Working Tree windows open.
14. Click Choose....
15. Browse to your Git working directory, created earlier when you first cloned the repository. Click on the top-level folder ("cardforge" or "cardforge-master") once.
16. Click Select.
17. Click Next.
18. Click Finish. Wait as SmartGit populates its Directories.
19. Recommendation: Make sure the main cardforge SmartGit window is active. Click the View menu, then clear the check mark next to Files from subdirectories. Because Forge has so many files, it does not make sense to show all of them at once.

How to Pull using SmartGit

Now, whenever the instructions say to "Pull" or "Push", use SmartGit instead of Eclipse EGit. To Pull:

1. Open or switch to SmartGit.
2. Click on the cardforge (or cardforge-master) working directory in the Directories pane on the left.
3. Click the Refresh button in the upper left.
4. Wait until the spinning "Refreshing" indicator at the bottom disappears.
5. Click the Remote menu, then Pull. The Pull window opens.
6. The defaults are OK: Merge fetched remote changes, Update registered Submodules, And initialize new Submodules.
7. Click Pull.
8. If prompted, accept Gitorious's RSA fingerprint is 7e:af:8d:ec:f0:39:5e:ba:52:16:ce:19:fa:d4:b8:7d. If that matches the value shown by SmartGit, click the affirmative response. Otherwise, click Cancel and check the Forge development forum to see if Gitorious's RSA fingerprint changed. (If it did, this document needs to be changed.)
9. If prompted with an SSH Authentication window:
   1. Click Choose....
   2. Browse to your home directory, within the .ssh folder.
   3. Click the dsa file that has your Gitorious key in it. It has a name like "id_dsa" or "id_alias_dsa". (You can check this location in Eclipse, Window menu, Preferences menu item, General category, Network Connections category, SSH2 category, General tab, Private keys text box.)
   4. Click OK in the file browser.
   5. Enter your passphrase. We do not recommend storing the passphrase.
   6. Click Login. (Braids had to click this twice for some unknown reason.)

Pay attention to the Output window in the lower right. If you get a green checkmark at the top of the Output pane that says "Fetch, merge, and commit", your pull was successful with no conflicts!

Otherwise, you will get a red X. SmartGit, being smart and all, will try to automatically merge changes in a file if they are in separate locations within the file. If there are any unresolved conflicts, it will tell you which files.

Before you can resolve conflicting files, you need to know what to look for. Each block of conflicts looks like this:

<<<<<<< HEAD 
Your text is here, 
usually in 
multiple lines.
=======
Repository's conflicting text is here, 
usually in 
multiple lines.
>>>>>>> origin/master

Your object is to transform each of these blocks into a sensible piece of code or text, without the less than, equals, and greater than characters.

When viewing the differences between files, green blocks are insertions, blue blocks are deletions, and red areas are changes. White areas are the ones that were not changed at all.

For each conflicting file:

1. In SmartGit, browse to the conflicting file.
2. Right click the file in the Files pane and choose Show changes.... A window opens with the name of the file.
3. Click on the first line in the file on the right.
4. Go to the Edit menu and choose Find.... The Find Text window opens.
5. Type seven less-than signs as the Text to Find:.
6. Click Find.
7. Edit the text in the file on the right side.
8. Look for more sequences of seven less than signs and fix them until none are left.
9. Click the File menu and choose Save.
10. Click the File menu again and choose Close.

For each auto-merged and conflicting file:

1. In SmartGit, browse to the conflicting file.
2. Right click the file in the Files pane and choose Show changes.... A window opens with the name of the file.
3. Click in the first line of the file on the right.
4. Read the file, paying special attention to the colored blocks of text. Make sure they are correct. You can navigate with the Goto Prev and Goto Next buttons. The blinking cursor's location in the right file indicates your current position.
5. If you encounter a change which looks more correct on the left side than the right, you can click the Take Left button. However, this is somewhat rare. Usually it is more appropriate to hand-edit the file on the right.
6. If you make a mistake, there is an Undo item in the Edit menu.
7. When you are done, click the File menu and choose Save.
8. Click the File menu again and choose Close.

Now go back to using EGit.

1. Go back to Eclipse.
2. Right click the ForgeGIT project, and click Refresh. (It is easier to find if you look for the yellow icon to its left).

In eclipse:

1. Test
2. Edit files

For each file exhibiting a red double arrow (almost a diamond) shape: Right click it, choose Team, then Add.

1. Once Eclipse refreshes the repository, you should eventually see no more red double arrows. You can now commit. Select all files (except res/gui/display_new_layout.xml and res/decks/JuzamjediCube.dck), even if you didn't modify them directly. These are the files that SmartGit merged.

Pushing is rather trivial.