===== Git - version control tool =====

'git' is an open source version control protocol available to all users on Pinnacle. It is used to keep track of changes made to files in a specific directory.  The basic commands used for this purpose are:

<code>
git init     - specify a directory for version control with git
git add      - add a file to a list of file for version control
git commit   - create a snapshot of the current version of files 
git branch   - create an alternate version of files 
git checkout - switch to the alternate branch (version of files)
git merge    - combine two branches into one
git log      - show a history of commits (snapshots)
git ls-files - show an index of files in the version control system
</code>


The following example shows step by step how to use git to keep track of changes made to your personal project on Pinnacle.

**1.** create a new project directory and initialize its management with git. (''git init'')

<code>
pinnacle-l1:pwolinsk:~$ mkdir project1
pinnacle-l1:pwolinsk:~$ cd project1/
pinnacle-l1:pwolinsk:~/project1$ git init
Initialized empty Git repository in /scrfs/storage/pwolinsk/home/project1/.git/
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**2.** create files in the project directory

<code>
pinnacle-l1:pwolinsk:~/project1$ nano file1
pinnacle-l1:pwolinsk:~/project1$ nano file2
pinnacle-l1:pwolinsk:~/project1$ cat file1
Some text in file1
pinnacle-l1:pwolinsk:~/project1$ cat file2
More text in file 2.
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**3.** add new files to the index (list) of files managed with git. (''git add <file_name>'',''git status'')

<code>
pinnacle-l1:pwolinsk:~/project1$ git status
# On branch master
#
# Initial commit
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	file1
#	file2
nothing added to commit but untracked files present (use "git add" to track)
pinnacle-l1:pwolinsk:~/project1$ git add file1
pinnacle-l1:pwolinsk:~/project1$ git add file2
pinnacle-l1:pwolinsk:~/project1$ git status
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#	new file:   file1
#	new file:   file2
#
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**4.** create a snapshot of the current state of all files tracked by git in the project directory. (''git commit -m "commit comment" <file_to_commit>'')
<code>
pinnacle-l1:pwolinsk:~/project1$ git commit -m "added initial text to file 1" file1
[master (root-commit) d4a8ab1] added initial text to file 1
 1 file changed, 1 insertion(+)
 create mode 100644 file1
pinnacle-l1:pwolinsk:~/project1$ git commit -m "added initial text to file 2" file2
[master cd7ebfa] added initial text to file 2
 1 file changed, 1 insertion(+)
 create mode 100644 file2
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**5.** modify file1 and file2 and create another snapshot of the current version of files.  (''git commit -a -m "commit comment"'' will commit all tracked files in a project with a single comment.)
<code>
pinnacle-l1:pwolinsk:~/project1$ echo "line 2" >> file1
pinnacle-l1:pwolinsk:~/project1$ echo "line 2 again" >>file2
pinnacle-l1:pwolinsk:~/project1$ git commit -a -m "added extra lines to file1 and file2"
[master db1a5f1] added extra lines to file1 and file2
 2 files changed, 2 insertions(+)
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**6.** review a history of commits. (''git log'')
<code>
pinnacle-l1:pwolinsk:~/project1$ git log
commit db1a5f1746b635bdbb73ebcc49dc3cf56a8ba2cf
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:47:48 2022 -0600

    added extra lines to file1 and file2

commit cd7ebfa2e6e67cf4e918be7bbba5c0e79af76036
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:45:02 2022 -0600

    added initial text to file 2

commit d4a8ab16fc53ba39b8bdf8f3b40db21681901f2f
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:44:55 2022 -0600

    added initial text to file 1
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**7.** Revert to a previous version of the files.  (''git checkout <commit_id>'')
<code>
pinnacle-l1:pwolinsk:~/project1$ cat file1
Some text in file1
pinnacle-l1:pwolinsk:~/project1$ cat file2
More text in file 2.
line 2 again
pinnacle-l1:pwolinsk:~/project1$ git checkout d4a8ab16fc53ba39b8bdf8f3b40db21681901f2f
Note: checking out 'd4a8ab16fc53ba39b8bdf8f3b40db21681901f2f'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at d4a8ab1... added initial text to file 1
pinnacle-l1:pwolinsk:~/project1$ cat file1
Some text in file1
pinnacle-l1:pwolinsk:~/project1$ cat file2
pinnacle-l1:pwolinsk:~/project1$ 
</code>

**8.** Go back to the latest version of files. (''git log --all'' shows all commits even those after the current commit version,''git checkout <commit_id>'')

<code>
pinnacle-l1:pwolinsk:~/project1$ git log
commit db1a5f1746b635bdbb73ebcc49dc3cf56a8ba2cf
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:47:48 2022 -0600

    added extra lines to file1 and file2

commit cd7ebfa2e6e67cf4e918be7bbba5c0e79af76036
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:45:02 2022 -0600

    added initial text to file 2

commit d4a8ab16fc53ba39b8bdf8f3b40db21681901f2f
Author: pwolinsk <gh_email>
Date:   Tue Mar 1 12:44:55 2022 -0600

    added initial text to file 1
pinnacle-l1:pwolinsk:~/project1$ 
pinnacle-l1:pwolinsk:~/project1$ git checkout db1a5f1746b635bdbb73ebcc49dc3cf56a8ba2cf
Previous HEAD position was d4a8ab1... added initial text to file 1
HEAD is now at db1a5f1... added extra lines to file1 and file2
pinnacle-l1:pwolinsk:~/project1$ cat file1
Some text in file1
line 2
pinnacle-l1:pwolinsk:~/project1$ cat file2
More text in file 2.
line 2 again
pinnacle-l1:pwolinsk:~/project1$ 
</code>

===== GitHub =====

Github is a popular platform for collaboration and data sharing.  It is based on the 'git' version control software.  Github.com is the central cloud based repository which provides storage for github user data.  The github CLI (command line interface) allows AHPCC users to move data between the github repository and the AHPCC cluster storage as well as share them with other AHPCC users. 

==== DART-ARP organization ====

A Github orgranization allow its members to collaborate and share data with each other.  AHPCC set up a github organization named **DART-ARP** (Data Analytics that are Robust and Trusted - Arkansas Research Platform).  

==== Joining DART-ARP ====

To become a member of DART-ARP organization and enable AHPCC/github integration, each user has to perform the following actions:

  - create a personal github account
  - add the AHPCC account SSH public key to the personal github account
  - accept and invitation to joing DART-ARP organization

A user executable script **''join-github-DART-ARP.sh''** is available to assist in performing these steps.


<code>
pinnacle-l7:user1:~$ /share/apps/bin/join-github-DART-ARP.sh 

   ============= JOIN AHPCC-DART github orgranization =============== 

  If you do not already have an active github.com account, before continuing
  with this script please visit:  

     https://github.com/signup

  Do you have an existing github account? [y/N] y

  Please enter you github username: user1
  Please enter your email: user1@uark.edu

  Github username: user1
  email:           user1@uark.edu
  Is this correct? [y/N] y
  Using a browser, please copy and paste your AHPCC SSH public key below into 
  your github.com account  
  (Account Profile->Settings->SSH and GPG Keys->New SSH key)


ssh-rsa AAAAB3NzaC1yc2weiHlqDTaj1nTryFTIagEnMs+d5WhEskL4JFvFo+Er7qwDV8bziQWFuUmFTYZWcuZpyLbWgf9b5oAjlmu7bUd2FIGi2jQDut0wI9Oq8tRdjY5nNNLw9zPY3e/+gRPV7bypg549E9gU5poaagKSq4QBqCEzuIUOIMhTgNzEQiVSmfgQg9OICX4njDJuaUxprQHxAz5F4wKd/lE8rSRV6e0MlE19kbByC8A+akfk8V/pzmBoRejeAwd+70dZALFHoMU90prl8enY0KsQHmApf0ucyi6La95qRtu32w== user1@ar.uark.edu


  Did you add your public SSH key above to your github.com account? [y/N] y
   Your github configuration (in /home/user1/.gitconfig):
[user]
	name = user1
	email = gh_email
[color]
	ui = true


  Logging into github...
  Please select "SSH, SKIP upload public key, authentication token" below
  Then please use a brower to open https://github.com/settings/tokens

? What is your preferred protocol for Git operations? SSH
? Upload your SSH public key to your GitHub account? Skip
? How would you like to authenticate GitHub CLI? Paste an authentication token
Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo', 'read:org'.
? Paste your authentication token: ****************************************
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as user1
Testing github integration with your AHPCC account...

github.com
  ✓ Logged in to github.com as user1 (/home/user1/.config/gh/hosts.yml)
  ✓ Git operations for github.com configured to use ssh protocol.
  ✓ Token: *******************
  

  Invitation to join DART-ARP github organization has been sent to user1@uark.edu
  Please follow the link in the email to join. 
pinnacle-l7:user1:~$ 

</code>