If you do not yet have an ORNL XCAMS userid, request one at https://xcams.ornl.gov
Login to code.ornl.gov using your XCAMS credential.
Send an email to the coherent list requesting one of the existing COHERENT group owners add your XCAMS id to the COHERENT group.
Adding an SSH key to your account
Before you can clone repositories or commit edits, you will need to add an SSH key to your https://code.ornl.gov account. Once you have access to the project(s), you can access https://code.ornl.gov, logging in using your ORNL XCAMS credentials with the LDAP login option.
Logged into code.ornl.gov, click on the link to your Profile in the upper right-hand corner of the screen; click on the "SSH Keys" section on the left-hand side of the Profile page; click "Add SSH Key" (see picture).
On the key addition page, you'll need to enter a name for the key you are adding and the public key you have generated (see below for key generation). To get your public key (on a Mac), open a terminal and type: cat ~/.ssh/id_rsa.pub. The public key is a block of text that should start with "ssh-rsa" and end with the text/email addressed supplied during key generation. After adding an SSH key to your ORNL Git account, you can test your access to the repository from a terminal using ssh -T email@example.com ; if things are working, you should see something along the lines of Welcome to GitLab, <your name>!, you should not be prompted for a password.
SSH Key generation
There's a helpful walkthrough to generating an SSH key linked on the key addition page and here:https://code.ornl.gov/help/ssh/README.
On a Mac, you can simply open a Terminal an use a variant of the following command appropriate for you: ssh-keygen -t rsa -C " firstname.lastname@example.org ". Press enter to use the default key location if you have never generated a key before (if you have, you may want to be careful about overwriting older keys). You can enter a passphrase for the key, or simply press enter through the passphrase prompts.
Joining a project
Once you have logged into code.ornl.gov, email Jason Newby and supply him with your XCAMS account username and ask to be added to one of the projects (e.g., DOE-HEP proposal).
Contributing using Git
Overview and general details
The remote repo address (the copy on the ORNL gitlab server) is given on the code.ornl.gov page for the project. For example, the address for the DOE proposal is email@example.com:COHERENT/coherent-proposal.git
Once you get started by acquiring a copy of a project using clone, the general development cycle is
- Make edits
- Merge (if necessary)
- Resolve conflicts if git can't
- Commit again to save resolutions
- Merge (if necessary)
If it has been a while since you last updated your local copy, it is a good idea to pull before editing.
Contributing using Sourcetree
Sourcetree is a freely-available app which integrates with Gitlab; find it [https://www.sourcetreeapp.com/ here]
Contributing using command line tools (Mac tested, probably not Mac specific)
Getting started: Getting a copy of a project (clone)
To begin contributing to a project on which you're a member, you must first clone the repository. To do this, enter the command git clone firstname.lastname@example.org:COHERENT/coherent-proposal.git from within the directory you'd like to use to contain your local working copy of the project. This will download the repo from ORNL.
Making an edit to your copy (commit)
Once you have made an edit to one of the files included in the project, you have to commit this change locally. To do this, from within the working directory, enter the command git commit -am 'I made a change that I am describing here' which registers the changes you've made to the tracked files. You should typically make the message descriptive.
Getting the updated version of a project (pull)
As others upload their changes, the ORNL copy will reflect those edits. You can update your local copy by using the command git pull If you've made edits locally and committed them using the commit command described above, you will be notified of potential conflicts with the edits made by others in the time since your previous pull: this process, integrating numerous edits, is known as a merge. Git will often handle merging gracefully, but it will ask you to enter a merge message by opening a VI editor and prompting you to enter some text. Move the cursor to an empty line and type "i", then enter a message; after you've entered a message to associate with the merge (such as, "merged citation edits with contributions from others"), press the escape key followed by "x" and the enter key. If Git notifies you that it hasn't handled merges well, you'll need to open some of the offending files and choose which versions to accept. See below.
Making your edits visible to everyone (push)
Once you've committed edits to your local copy, you can upload them to the ORNL copy so that the changes are present in the version available to everyone. It is recommended that you first update your copy to the most-recent version on the ORNL server using the pull command described above: this way, you limit the chance that you undo changes made by others.
Once you're ready to share your copy, this is accomplished by using the command git push
Handling merge conflicts
If Git can't easily decide how to merge edits, it will leave resolution up to you. It will notify you on the command line of the identity of files which need manual resolution. Usually, when you do a pull after making commits, it will merge on its own, displaying text something along the lines of:
user@local:coherent-proposal$ git pull remote: Counting objects: 12, done. remote: Compressing objects: 100% (12/12), done. remote: Total 12 (delta 9), reused 0 (delta 0) Unpacking objects: 100% (12/12), done. From code.ornl.gov:COHERENT/coherent-proposal. 1040841..3a1585f master -> origin/master Auto-merging proposal/Ge.tex Merge made by the 'recursive' strategy. proposal/Ge.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
However, if it cannot figure out how to reconcile the edits, it will display something similar to:
user@local:coherent-proposal$ git pull remote: Counting objects: 4, done. remote: Compressing objects: 100% (4/4), done. remote: Total 4 (delta 3), reused 0 (delta 0) Unpacking objects: 100% (4/4), done. From code.ornl.gov:COHERENT/coherent-proposal. f086aea..c392192 master -> origin/master Auto-merging proposal/refs.bib CONFLICT (content): Merge conflict in proposal/refs.bib Automatic merge failed; fix conflicts and then commit the result.
In the event a file has conflicts which Git doesn't resolve, you must open the file named (in the case above, refs.bib had a problem) in a text editor. Git will insert text around the issue identifying the content present on the remote and local repositories. Your task is to remove all of the conflicts and associated conflict-marking text and replace it with the appropriate resolved version. You might see something like this, somewhere in a hypothetical "budget.tex" file:
Graduate students should be paid <<<<<< HEAD ? =========== lavishly. >>>>>> (some branch identifier)
In this case, you have (correctly) asserted that grad students should be compensated well, but the main repository reflects an uncertainty regarding the nonzero value of students. To resolve this conflict, you would open "budget.tex" in an editor, find the section with this text, and edit it such that it reads .
Graduate students should be ``paid".
to lamentably-but-correctly reflect the compensation of grad students. Upon saving this file, you would make another commit along the lines of git commit -am 'resolved merge issue in budget.tex regarding grad students', and then push.
Some links which may describe this better: [https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/]