-
Notifications
You must be signed in to change notification settings - Fork 2
Using Git in DjLu
DjLu allows you to store your papers library in a git repository. This offers various advantages:
- You stay in control of your library (DjLu does not store anything outside of your repository), so you can always keep your data and leave (we only use very simple human readable files).
- You can sync your git repo on your personal computer and keep an offline access to it.
- You can edit your library manually (add, remove, edit papers stored in your library), which can be especially convenient to take notes.
To make use of this feature properly you must read this page, because as you could have guessed, this great power comes with great responsibilities. If you do not edit your library properly, it will produce errors or weird behavior on the DjLu web app.
To setup git for your DjLu account, you need to go to the Settings of your account and follow the instructions there.
Note: To use git with DjLu, your DjLu account must have the correct rights. If you don't the information will show up in the Settings form and you will have to ask your DjLu admin to set it up.
The principle of the setup is that the DjLu server will clone your git repository from the git clone path you will provide it. To be able to do so, the server will try to clone the repository through SSH and will authenticate itself using an SSH key.
Therefore, for the process to work, you must allow read / write access to your git repository to the SSH key of the DjLu server. To do so, you can get the SSH public key that the server will use for your account in the Settings.
On GitHub, we suggest you use the Deploy Key feature.
Each paper in your library consists in a folder or a file in your git repository depending on the type of paper.
As you know, there are two types of papers allowed in DjLu, either full references (with structured data, bibtex and notes) or temporary short references that only consists in a blob of text to allow quick add of papers in your library.
Full references are contained in folders while short references are simple text files.
Each paper has an ID that must be letters and numbers only. The name of the paper's folder or file must be the ID of the paper, and can be followed by an underscore followed by whatever characters you want.
If it's a short reference, the filename must ends with .txt.
Example: A paper with the ID JohnDoe2016 can be stored in a folder called
JohnDoe2016 or JohnDoe2016_Title_of_the_paper for example (or a paper in a
file ending with .txt).
Of course, papers identifiers must be unique in your library. An ID clash will produce unexpected results.
A full reference paper is stored in a folder starting with its identifier. This folder contains different files:
- A JSON file that contains the metadata about the paper that will be displayed on DjLu's interface (title, authors, publication info, tags, etc.)
- A BibTex file that contains the BibTex entry of the paper. We highly suggest the entry to use the paper's ID as citation key.
- An optional Markdown file with your notes about the paper.
Each of these files must be named with the paper ID followed by the correct
extension (.json, .bib, .md). For example JohnDoe2016.json for the
example above.
The JSON file can contain the fields described below:
{
"title": "Paper's title",
"authors": ["LastName, FirstName", "LastName, FirstName", ...],
"year": "2016",
"date_added": "2016-04-22 15:48", // YYYY-MM-DD HH:MM
"in": "Journal Name", // abbreviation suggested
"url": "...", // URL to the PDF
"rating": 4.3, // rating of the paper (out of 5)
"tags_reading": ["reading", ...], // tags about reading status
"tags_content": ["deep", ...], // tags about the content of the paper
"tags_notes": [...], // tags to take short notes about the paper
"secret": "vknUXt5R8YVG3fqL5JyaXjrY" // secret key to allow public access to
// your ref. Paper will be private if
// `secret` is absent or empty
}Short references are a single file which name starts with the ID and ends with
the .txt extension. This file contains raw text that will be parsed as
Markdown to allow some very light markup.
When using git for DjLu, you will of course have to handle all git actions both on the DjLu UI and on any other place where you want to sync / edit your library.
For now, DjLu UI only gives you access to 3 git actions:
- Clone from the Settings
- Commit of all the modifications done on the UI
- Pull from the remote git server
DjLu do not provide tools for more advanced git actions and for conflicts resolution. That is why for now, you must absolutely avoid producing conflicts by making sure any commit made on the remote has been pulled before making modifications. If you produce conflicts, contact your DjLu administrator.
When you manually edit your library, the important things you should be careful about are:
- making sure to keep the JSON file of the papers valid. If you're not sure
if it's still valid, put it in an online JSON parser. Especially please mind
trailing commas which are not allowed in JSON
(e.g. you must remove the last comma in
{"k1": "v1", "k2": "v2",}) and don't forget to put double quotes around keys and strings (single quotes are invalid). - avoiding key clash by having multiple papers with the same key
- avoiding to produce git conflicts on the DjLu server by pushing your changes made on the server before making local edits and pulling the repo before making changes on the server.
If you see weird behavior on the web app, you can try to solve it yourself by reverting the last commit(s) or fixing the errors. You you still have trouble, ask your DjLu administrator.