First post in this series: Introduction to DbTradeAlert
Previous post: Install Git
Of course setting up a public Git repository is optional when you create a development environment. I actually did this only when the project was nearly finished – that’s why it’s name “DbTradeAlert” is sprinkled all over this post.
Publishing to a public repository makes the code available to others and creates a free backup facility.
There are various hosting services for Git repositories with the most prominent by far being GitHub. Others are BitBucket, Source Forge, CodePlex, and Google’s recent creation Cloud Source Repositories.
I went with GitHub mostly because it’s the most prominent and I want to learn more about it. A potential problem is that only public repositories are free on GitHub but that’s not a problem for DbTradeAlert.
8. Create a GitHub Account
Creating a GitHub account is straightforward – only username, email address and password are required. The default plan of unlimited public repositories for free is sufficient for public projects like DbTradeAlert.
Now you need to decide whether you want to use HTTPS or SSH to access GitHub:
- Using HTTPS requires no further preparations as it uses your GitHub account’s credentials. To use SSL you need to generate keys and specify them in your GitHub account as well as in TortoiseGit.
- You can use a credential helper with HTTPS so you don’t have to enter name and passwort for every push.
- The HTTPS port will always be open while the SSH port may be closed.
- With SSH you can use per-project credentials
- If someone finds out your SSH credentials they still cannot access the account.
Both protocols are secure and if you implemented SSH access you and everyone accessing the repository can still use HTTPS. GitHub have changed their mind about which protocol they prefer and currently recommend HTTPS.
If you will use HTTPS just proceed to add a repository.
To use SSH first generate an SSH key:
- Start C:\Program Files\TortoiseGit\bin\puttygen.exe
- In PuttyGen click Generate and move your mouse cursor to generate randomness until the key has been generated
- Optionally enter and confirm a key passphrase – caching aside you’ll have to enter that password each time TortoiseGit connects to GitHub
- Copy the generated key comment
- Click Save private key
- Use the copied key comment to name the file – important:
- Do NOT save this file in the repository as you don’t want your private key to become public!
- Be shure to backup this file
- Keep the PuttyGen window open
Now go back to your GitHub account in the browser:
- In the top right corner select Settings from the dropdown list
- In the Settings page select SSH and GPG keys
- In the SSH and GPG keys page click New SSH key
- Copy the key comment from PuttyGen and paste it into the Title field
- Copy the public key from PuttyGen and paste it into the Key field – make shure to copy all of it as Ctrl+A doesn’t work
- Click Add SSH key
- Enter your GitHub password to continue
- Close the PuttyGen window
After a moment you’ll get an email informing you about the new SSH key to prevent misuse.
9. Add a Repository
DbTradeAlert is a somewhat special case because the project already exists in a local repository. It’s easier to create the project in GitHub and then connect TortoiseGit to it.
To add a repository to your GitHub account:
- Go to https://github.com/
- Log in
- Click New repository
- On the Create a new repository page
- Enter Repository name – “DbTradeAlert for Android” in my case which results in a DbTradeAlert-for-Android repository
- Optionally enter a description
- Leave Public checked – you need a paid plan to select Private
- Initialize this repository with a README: good idea as this file is displayed on the repository’s landing page
- Add .gitignore: leave this at None because the project already has a .gitignore file
- Add a License: I chose Apache 2.0 because it explicitly states that no trademark rights are granted and changes to the code must be noted. Android uses the same license.
- Click Create repository
Initializing the repository with a README is mandatory for creating an empty project simply because Git cannot handle empty folders.
10. Configure TortoiseGit to Connect to the new Repository
Before TortoiseGit can use the remote repository you have to tell it how to connect:
- In the project directory’s context menu select TortoiseGit | Settings
- Click OK in the message window telling you about Git’s hierarchical configuration
- In the Settings window
- In the left pane select Git | Remote
- In the URL field
- To use HTTPS copy the repository’s URL – https://github.com/ghdbre/DbTradeAlert-for-Android in my case
- To use SSH create an approproiate URL – email@example.com:ghdbre/DbTradeAlert-for-Android.git in my case
- The remote field will be initialized with “origin” automatically
- If you use SSH specify the file with your private key in the Putty key field
- Click Add new/Save – the Remote list has a new entry named “origin”
- Click OK
11. Publish the Project
Until now Git has only commited changes to the local repository. Now it’s time to commit to the remote repository. Because having two kinds of commits would be confusing committing to the remote repository is called “push”. Getting changes from the remote repository is called “pull”.
11.1 Pull New Files from GitHub
If you had GitHub create files – like Readme.md or LICENSE – in the new repository you’ll need to pull them into your local repository first:
- In the project directory’s context menu select TortoiseGit | Pull …
- In the Pull window
- Remote should default to “origin”
- AutoLoad Putty Key should be checked
- Click OK
- You’ll get a TortoiseGitPlink security alert – click Yes to always trust the host
After that TortoiseGit downloads the new files to your local repository and you are ready to push your project. Close the Progress window.
11.2 Fill Readme.md
Readme.md is the file that’s presented right on your GitHub project’s home page and it should contain the reason why anyone would download your project. I chose to fill it with the introduction to DbTradeAlert for end users – just copied everything from the web page and applied markdown to it. There are sites on the web that provide a preview for the result.
After that commit Readme.md to the local repository.
11.3 Push Project to GitHub Repository
Finally push the project to the new GitHub repository:
- In the project directory’s context menu select TortoiseGit | Push …
- In the Push window
- Ref | Local should default to “master”
- Destination | Remote should default to “origin”
- AutoLoad Putty Key should be checked
- Click OK
If you use HTTPS you’ll have to enter name and password for your GitHub account.
After that TortoiseGit compresses and uploads the project’s files to your GitHub repository. Close the Progress window.
To check the result go back to your GitHub repository and refresh the page – you should now see your project’s files and the contents of Readme.md below that list.
11.4 Add an Image to GitHub’s Landing Page
The text in Readme.md might not be enough to get people interested but a screenshot is worth a thousand words. But where do you store that file?
Most people will want to store it on GitHub itself for ease of maintenance. And the easiest way to do that is to create an issue where you attach the screenshot:
- In the project’s GitHub page open the Issues tab
- In the Issues tab click New issue
- Enter a description like “Screenshot for landing page”
- Drag your screenshot into the input area
- Copy the resulting URL (https://cloud.githubusercontent.com/assets/<endless string of characters>.png)
- Click Submit new issue
- Close the new issue
Now that you sneaked the screenshot on GitHub’s server add a link to it in Readme.md:
- Open Readme.md in an editor
- Enter the link
- in markup: ![App at work](https://cloud.githubusercontent.com/assets/<endless string of characters>.png) if you don’t need formatting
- in HTML: to enjoy full control
- Commit the change
- Push the change to GitHub
Refreshing your project’s landing page should now show the new eye-catcher.
Note that this is a totally unofficial procedure and may stop working in the future. GitHub also provides personal / organizational and project pages if you need more than just a screenshot and a bit of text.
Next post: Create the Application
- Open source licenses compared: http://choosealicense.com/licenses/
- Why does GitHub recommend HTTPS vs. SSH?: http://stackoverflow.com/questions/11041729/why-does-github-recommend-https-vs-ssh
- Using HTTPS or SSH with GitHub: http://stackoverflow.com/questions/18520061/using-https-or-ssh-with-github
- Is there a way to skip password typing when using https:// on GitHub?: http://stackoverflow.com/questions/5343068/is-there-a-way-to-skip-password-typing-when-using-https-on-github
- Creating folders inside github.com repo without using Git: http://stackoverflow.com/questions/18773598/creating-folders-inside-github-com-repo-without-using-git
- Markdown Cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
- Markdown Live Preview that can handle HTML anchor definitions: http://tmpvar.com/markdown.html