Skip to content
Manko10 edited this page Sep 27, 2011 · 6 revisions

SmartGit is a graphical tool for Git, which makes it very easy to contribute to the documentation project. It is available for Windows, Linux and Mac and it's free for non-commercial use. Only the setup is a bit tricky, but when you follow this guide step by step, that shouldn't be a problem.

Installation

First go to the SmartGit website and download the right package for your system. Windows users now need to unpack the zip file and run the installer, Linux/Unix users just need to unpack the tar.gz file without any further setup routine.

Once you've set up everything, start the application (Linux users find the start script at bin/smartgit.sh).

First of all you need to accept the license agreement. After that check "Non-commercial use only" if you haven't bought a license for commercial use. In the next step SmartGit wants to know the path of the Git executable. If there is already a path filled in (on Linux it's mostly something like /usr/bin/git), you might just click Next, but probably you haven't installed Git yet.

If that's the case, you need to install Git now. Linux users may install it via their package manager (normally the package is named git or git-core), Windows users need to click the link provided by SmartGit and install msysgit from that location. Max OS X users can either use the git-osx-installer or Macports. For detailed setup instruction, follow the steps described in the installation section here thoroughly. When done, enter the path the Git executable and click Next.

Then SmartGit asks you whether you want to use your system SSH or whether SmartGit should handle SSH by itself. If you're on Linux, you may choose system SSH if you know what you do, otherwise the default setting might be the best.

In the next step, enter your name and an email address. You may leave this blank, but I recommend you not to skip this step.

On the next page Choose GitHub as your hosting provider and enter your GitHub login credentials. When you click next, SmartGit will ask you whether you want to encrypt the password with a master password. It's up to you whether you want to do that or not. Just be aware that if you don't your GitHub password will be saved in plain text on your hard drive.

Now the basic setup is done. Click Finish.

Clone the repository

When you start SmartGit the first time, you'll be ask to set up a repository. Check Clone existing repository and click OK. Now leave Remote Git or SVN repository checked, click Select and then choose Select from GitHub. Mark your repository and click Select, then click Next.

Now you need to set up an SSH key if you haven't got one (if you don't know what it is, you don't have one). Follow the instructions in the section Generate SSH key from the Git setup guide. When you're finished, enter the path to your private key (the id_rsa file), enter the passphrase if you've set one and click Login.

Now you need to specify the directory where you want your local working copy to be. Select a location of your liking and click Finish.

Using SmartGit

Phew! Setup is done, now it becomes easier. When everything's set up properly, you should see SmartGit fetching all the files from your GitHub fork. When it's finished, you can double click any file to edit it. Alternatively you could of course also open the file directly from your file manager (Explorer on Windows). All the files you see in SmartGit are just normal files in the directory which you chose as your local working copy.

SmartGit should now look like this (number and names of the files may of course be different): SmartGit set up properly

Editing and committing

When you have edited a file, click Refresh to tell SmartGit that something's changed. Now all files which changed should be marked red:

SmartGit - Changes marked red

Select all the files you have edited and click Commit. Enter a few descriptive words (e.g. Fixed typo or Added article xyz) and click Commit.

Publishing changes

When you've committed your files, you told Git to track the changes made but you haven't published anything yet. To push all the changes to your GitHub fork you have to click Push. If you haven't edited any branches (if you don't know what branches are, you most likely haven't), leave the default Current branch checked and click Push.

Now SmartGit has pushed all your changes to your GitHub fork. Now you can send a Pull Request to the official repository by clicking the Pull Request button on GitHub if you want your changes to appear in the official docs (see below).

Keeping your copy fresh

Not only your copy advances. Also the official repository does. So it is necessary to pull in changes from the official repository from time to time. Unfortunately, SmartGit doesn't make it too easy to do this at the moment. I hope, that will be changed in future versions.

First you need to set up the official repository as a remote. Note: you need to do this only once! Click on Remote in the menu bar and then on Manage remotes. There hit the Add button and enter upstream as the name and git://github.com/Manko10/InsertCoin-Docs.git as the URL. Click Add and you're done.

SmartGit - Add remote

Now you can click Pull on the tool bar, select upstream as the Remote repository and click Pull and Git will start pulling from the official repository.

SmartGit - Pull from upstream

Until now, not much has changed. Once Git has finished, you need to click Merge. Make sure that under Showing Branch(es) the branch upstream/master is selected. If not, click Select -> Other Branches -> upstream/master and the Select. Now make sure “If possible, move just the branch pointer forward (fast-forward)” is checked and click Merge. if no conflicts occur, your copy should now be up to date.

SmartGit - Merge upstream

Repeat the last two steps (pull and merge) every time you want to update your copy. Note, that this only updates your local copy. To Update your GitHub copy as well, just do a Push after this update procedure.

Sending a Pull Request

If you have done modifications you want to appear in the main repo and on the staging website, send a Pull Request by clicking the Pull Request button here on GitHub. Write some informative description and we'll see if we can merge your modifications. Be prepared for some further discussion in the discussion thread for your Pull Request.

Be aware that we can only merge changes you have pushed to your GitHub repo. Revisions which only exist in your local copy are only visible to you.

If you have sent a pull request but then perceive you forgot something, just make your new modifications, commit and push as usual. As long as we haven't merged anything, your new changes will be added to the open Pull Request automatically.