If you know how gitHub works and you have git installed on your machine, you can follow these simple steps to get the .bib files. If you have not used gitHub or git before please see below for more detailed instructions.
- To grab a copy simply type:
git clone git@github.com:ExoMol/bib.git(you must have a GitHub account) - This will create a local copy of all the bib files on your machine
- You can add to the bib files as normal (although please adhere to the naming conventions)
- To submit your changes back to gitHub:
git add .(orgit add <file 1> <file 2> <file 3>)git commit -m "<your message here>"git pullgit push
- Your changes will now be added to the global gitHub repo
(Note: you must be a collaborator to add directly to the gitHub repo. If you are not a collaborator, the best option is to fork the gitHub repo instead and then submit a pull request)
If you get a permission denied (publickey) error, please follow the steps below:
cd ~/.ssh- There should be a file called
id_rsa.pub- open this and copy the contents - On the gitHub website, go to "Settings" and the "SSH and GPG keys" tab
- Create a new SSH key, paste in the contents of
id_rsa.puband save
(Thanks to Katy for pointing this out - also see link here for more info)
If you would like a copy of the .bib files on your local machine please follow the below instructions to download them. If not they can still be found on the shared folder in the usual place.
To clone (download) the .bib files from this repository you will first need git installed on your machine. It is more than likely that you may already have git installed on your machine. To check, type the following command in your terminal:
$ git --version
If it is installed you will see something like this:
git version 2.7.4
If it is not installed, see Install Git
Please note you will need a GitHub account to collaborate in the ExoMol bib project. GitHub accounts can be created here.
You only need to set the following up once i.e., if you have not used GitHub or git before. The first thing you should do when you install Git is to set your user name and email address. This is important because every Git commit uses this information, and it’s immutably baked into the commits you start creating:
$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com
Note, that you have to use the email address that you registered your GitHub account with. You can check the changes have been made by typing:
$ git config --list
First locate to the directory on your local machine where you would like to clone the .bib files:
$ cd Documents/ExampleDirectory/
Then type the following command into the terminal:
$ git clone git@github.com:ExoMol/bib.git
You should see something like this (if it is successful):
Cloning into 'bib'...
remote: Counting objects: 570, done.
remote: Compressing objects: 100% (77/77), done.
remote: Total 570 (delta 13), reused 88 (delta 12), pack-reused 481
Receiving objects: 100% (570/570), 12.64 MiB | 483.00 KiB/s, done.
Resolving deltas: 100% (188/188), done.
Checking connectivity... done.
You can check the .bib files with ls -1 ./bib and you should see something like this:
emol
exomol
journals_astro.bib
journals_phys.bib
jt
MARVEL
plasma
README.md
rmat
RmatReact
If so then you have successfully cloned .bib git repository.
Chances are, if you are making amendments to a certain .bib file then others will also need this change as well. The process to change a bib file, and upload back to GitHub repo (folder) is as follows:
- Edit/Create file as normal
- Make change(s) and save
- Stage (
git add) changes locally - Commit (
git commit) changes - Push (
git push) changes back to the server
Once you have sent the request to push, these changes will be merged to the master copy on GitHub and available for others to download!
Now at this point, if you have are not sure about what version control software is, or what the basics of git are then I recommend this guide. That said, all the information you will need should be in this guide.
In this example we will modify an existing file test.bib:
First check you are working with the most up-to-date copy (most recent commit)
$ cd Documents/ExampleDirectory/bib/
$ git pull
Already up-to-date.
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
Then modify the file (using any program vim/nano/gedit/notepad etc.):
$ vim test.bib
Make your changes and then save. In this case I add a line to the file "Hello World!". Running the command git status will verify any changes made to the local version.
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: test.bib
no changes added to commit (use "git add" and/or "git commit -a")
The key line here is "Changes not staged for commit". This moves us onto our next point - stage (git add) changes locally.
Staging changes means that you are preparing to commit your file. You can stage changes at anytime. They will only be committed when you run git commit. This is useful when changing multiple files. You can add them individually or all together at the end. In this example we are only making changes to one file test.bib. To stage the changes we can do the following:
$ git add test.bib
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: test.bib
The key line here is now "Changes to be committed". We can now get ready to commit our changes to local repo (folder).
For a change to be added to GitHub it must first be committed. A commit is like a snapshot of a folder and all of its contents. After you the changes have been committed they can then pushed back to GitHub (git push). To commit your staged changes use git commit -m "<your message here>". Where <your message here> can be a short description of the changes made. See below for an example:
$ git commit -m "made changes to test.bib"
[master 34f64ba] made changes to test.bib
1 file changed, 1 insertion(+)
create mode 100644 test.bib
Before you push changes back to GitHub it is always a good idea to run git pull first (this helps to avoid errors on the off chance someone else pushes their changes before you can submit).
$ git pull
Already up-to-date.
This will update if changes have been made or simply state that the folder is already up-to-date. You are now ready to push your changes back to the server:
$ git push
warning: push.default is unset; its implicit value has changed in
Git 2.0 from 'matching' to 'simple'. To squelch this message
and maintain the traditional behaviour, use:
git config --global push.default matching
To squelch this message and adopt the new behaviour now, use:
git config --global push.default simple
When push.default is set to 'matching', git will push local branches
to the remote branches that already exist with the same name.
Since Git 2.0, Git defaults to the more conservative 'simple'
behaviour, which only pushes the current branch to the corresponding
remote branch that 'git pull' uses to update the current branch.
See 'git help config' and search for 'push.default' for further information.
(the 'simple' mode was introduced in Git 1.7.11. Use the similar mode
'current' instead of 'simple' if you sometimes use older versions of Git)
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 292 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To git@github.com:ExoMol/bib.git
7a9cefd..34f64ba master -> master
Notice that there is a warning message. This can be ignore or you can run the following command to remove it:
git config --global push.default simple
The important part is the following:
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 292 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To git@github.com:ExoMol/bib.git
7a9cefd..34f64ba master -> master
Now your changes will be available for everyone to download from the main GitHub repository.
If git is not installed, you can run the following commands in terminal to install. In Ubuntu this is as simple as:
sudo apt-get update
sudo apt-get install git
Or in ScientificLinux it is:
yum update
yum install git
On the Windows OS, try the GitHub Desktop App: https://desktop.github.com/