View source for Basic GitHub Tutorial

== Introduction ==
[https://github.com/ GitHub] is a web-based <span class="plainlinks">[https://en.wikipedia.org/wiki/Git Git]</span> <span class="plainlinks">[https://en.wikipedia.org/wiki/Repository_(version_control) repository]</span> <span class="plainlinks">[https://en.wikipedia.org/wiki/Internet_hosting_service hosting service]</span>. It offers all of the <span class="plainlinks">[https://en.wikipedia.org/wiki/Distributed_version_control distributed version control]</span> and <span class="plainlinks">[https://en.wikipedia.org/wiki/Version_control source code management]</span> (SCM) functionality of <span class="plainlinks">[https://en.wikipedia.org/wiki/Git Git]</span> as well as adding its own features. It provides <span class="plainlinks">[https://en.wikipedia.org/wiki/Access_control access control]</span> and several collaboration features such as <span class="plainlinks">[https://en.wikipedia.org/wiki/Bug_tracking_system bug tracking]</span>, <span class="plainlinks">[https://en.wikipedia.org/wiki/Software_feature feature requests]</span>, <span class="plainlinks">[https://en.wikipedia.org/wiki/Task_management task management]</span>, and <span class="plainlinks">[https://en.wikipedia.org/wiki/Wiki wiki]</span>s for every project (from wikipedia [https://en.wikipedia.org/wiki/GitHub])

We use GitHub to manage and develop software collaboratively. Currently we have two such software packages on GitHub: [https://github.com/dgary50/eovsa eovsa] (for EOVSA operation and calibration) and [https://github.com/binchensun/suncasa suncasa] (for processing and visualizing radio imaging spectroscopic data). Tons of detailed tutorials can be found on [https://github.com Github.com] and elsewhere. In the following, some very basic instructions are provided (to busy/lazy people like you!) to demonstrate the minimal use of GitHub.

== Understand the GitHub Workflow ==
A nice and precise description is available [https://guides.github.com/introduction/flow/ here].

== Setup GitHub ==
=== Register a GitHub account ===
Too straightforward! Just follow the instructions [https://help.github.com/articles/signing-up-for-a-new-github-account/ here].

=== Setup SSH for remote access ===
We need to set up remote access to your online GitHub repository. There are multiple methods of doing this, but I am used to the SSH method. Detailed instructions are available [https://help.github.com/articles/generating-an-ssh-key/ here]. But here are my steps of doing this. First, check if you already have SSH keys.
<pre>
ls -al ~/.ssh
</pre>
By default, the filenames of the public keys are one of the following: id_dsa.pub, id_ecdsa.pub, id_ed25519.pub, id_rsa.pub. If you don't have an existing public and private key pair, or don't wish to use any that are available to connect to GitHub, then generate a new SSH key.
<pre>
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
</pre>
You'll be prompted for a few questions. Just press enter to advance. Before adding the new SSH key to the ssh-agent, check if your ssh-agent is running:
<pre>
eval "$(ssh-agent -s)"
</pre> 
If it says something like "Agent pid 59566", you are good. Now add the SSH key:
<pre>
ssh-add ~/.ssh/id_rsa
</pre>
Now that you have a SSH key on your machine, you can proceed and add it to GitHub following [https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ these instructions].

== Minimal use of GitHub ==
=== Start your own repository from scratch ===
Suppose you have a new brilliant idea and want to convert it to working codes. You decided to make up a repository to put your codes in. First, go to GitHub.com and create a new repository there called "myprecious". Then open a terminal window on your computer, create a directory named "myprecious", and add some descriptions in a file called "README.md"
<pre>
mkdir myprecious
cd myprecious
echo "# myprecious" >> README.md
</pre>
First, we need to initialize it to be a git repository
<pre>
git init
</pre>
You are so excited and pull an all-nighter putting your codes together (remember to save them!). Now you have a lot of stuff in your directory "myprecious". You can now add them into the git repository and commit the changes:
<pre>
git add .
git commit -m "a message describing your commit"
</pre>
You are proud of yourself and decide to push all the codes to GitHub.com to let everyone see. But before that, define your remote repository on GitHub:
<pre>
git remote add origin https://github.com/your_github_account/myprecious.git
</pre>
Check your remote destinations:
<pre>
git remote -v
</pre>
You'll see something like this:
<pre>
origin	https://github.com/your_github_account/myprecious.git (fetch)
origin	https://github.com/your_github_account/myprecious.git (push)
</pre>
Now you can push your codes to Github and complete your edits:
<pre>
git push origin master
</pre>

=== Develop codes collaboratively ===
Now suppose you would like to collaborate with others to develop some brilliant software package. Detailed instructions can be found from [https://help.github.com/articles/fork-a-repo/ this link]. But here are just some basic steps. Let us use our [https://github.com/binchensun/suncasa suncasa] package as an example. First, go to [https://github.com/binchensun/suncasa the original owner's package page] and click "Fork" in the upper-right corner of the page. Now you have the same repository under your own GitHub account. Say the url to your forked repository is https://github.com/your_github_account/suncasa. Now clone a copy of the GitHub repository to your machine:
<pre>
git clone https://github.com/your_github_account/suncasa
</pre>
After that, you will have a folder named "suncasa" under your current directory. Everything in this folder are exactly the same as the online repository. The remote destination should have already been set. You will have something like this after running
<pre>
git remote -v
origin	https://github.com/your_github_account/suncasa.git (fetch)
origin	https://github.com/your_github_account/suncasa.git (push)
</pre>
Note you are now working under the forked repo, or '''your own copy''' of the original repository. You can make any changes you like (because this is your own repo!). After all the edits, you can add, commit, and push all the changes you made to your own forked repo (same as those in the previous section). This repo is now totally independent with the original one (it has been "forked" away, indeed). But in the mean time, the original owner may make additional changes since you cloned it, and sometimes you would like to keep up with those changes. To sync those changes to your own forked repo, we can firstly add the original owners GitHub repo (or "upstream" repo) as a remote destination:
<pre>
git remote add upstream https://github.com/binchensun/suncasa.git
</pre>
Now your "git remote -v" output would be like this:
<pre>
origin	https://github.com/your_github_account/suncasa.git (fetch)
origin	https://github.com/your_github_account/suncasa.git (push)
upstream 	https://github.com/binchensun/suncasa.git (fetch)
upstream 	https://github.com/binchensun/suncasa.git (push)
</pre>
The first two lines are your own forked Github repo, and the 3rd and 4th lines are the original owner's repo. To do the sync, you run the following commands:
<pre>
git fetch upstream
git checkout master
git merge upstream/master
</pre>
The first command "fetch"es all info from the upstream repo (from the original owner). The second command makes sure you are working under your own local forked repo. The third command compares the local commits with the remote repo and merges all the changes.

Once you've done all the improvements and get very proud of yourself, certainly you want to let the original owner know and ask him/her to update the codes (because now your repo is better than his/hers!). To do this, you can [https://help.github.com/articles/creating-a-pull-request/ submit a pull request via GitHub]. The original owner will receive an email notifying that a pull-request has been issued. (S)he will review the changes, have a discussion with the proposer, make any additional commits if necessary, and finally accept the pull request. After that, everything are updated. The original and forked repos merge together and another round of development may start.

====what to do with conflicts?====
In github's pull request page, you can click the "Resolve Conflict" button, which brings you to a page with markups to indicate the conflicts. Edit the file as appropriate to resolve the conflicts. Then you will be brought back to the pull request page, commit the changes, and merge pull request.