Welcome to PyGitrefer, your daily assistant for effortlessly managing bibliographic information directly within your GitHub repositories!
Say goodbye to messy spreadsheets and hello to a streamlined, version-controlled, and collaborative approach to keeping your research references in order.
PyGitrefer is a Python package designed to make managing your references on GitHub a breeze. It allows you to:
- Manage References: Easily add new references from DOIs or PDFs, even extracting information automatically if DOI is missing. You can also add, edit, and remove references manually.
- Attach Files: Link PDFs, notes, or any relevant files directly to your references.
- Organize with Tags: Categorize your references with custom tags for quick filtering, searching and custom exports.
- Version Control: Leverage the power of Git to track any changes to your references.
- Collaborate with Ease: Share your references with collaborators, keep track of changes, and maintain a clean and consistent bibliography.
- Export in Multiple Formats: Generate citations in BibTeX, APA, RIS, and more!
PyGitrefer is a perfect tool for researchers, students, and anyone who wants to keep their references organized, accessible, and up-to-date. You can easily integrate it into existing repositories or start fresh with a dedicated bibliography repository.
- Python 3.11+
Warning
With Python 3.12+, building the pymupdf package may fail. If you encounter this issue, please use Python 3.11 for now.
-
Install directly from GitHub:
pip install git+https://github.com/nken-eccs/PyGitrefer.git
-
Install using pip (coming soon):
pip install pygitrefer
You need to set up the following environment variables before you can start using PyGitrefer:
- GitHub Personal Access Token (
GITREFER_TOKEN):- Generate a personal access token on GitHub with
reposcope.
- Generate a personal access token on GitHub with
- Repository Information (
GITREFER_REPO):- Determine the owner and name of your GitHub repository (e.g.,
owner_name/repository_name). - If you start with a new repository, please create a repository first before initializing PyGitrefer!
- Determine the owner and name of your GitHub repository (e.g.,
Note
You can find this information in the URL of a repository on GitHub. For example, in the URL https://github.com/nken-eccs/PyGitrefer, the owner_name is nken-eccs and the repository_name is PyGitrefer. Even though the owner name is not your username, you can still access the repository with your personal access token if you are a collaborator.
- Gemini API Key (Optional) (
GITREFER_GEMINI_API_KEY):- If you want to use the AI-powered reference extraction feature, please get an API key from Google AI Studio. Anyone who has a Google account can sign up for free.
Note
Currently, Gemini 1.5 Flash is set as the default model. You can make requests up to 1500 times per day [source].
The easiest way to set these environment variables is to create a .env file in the root directory of your project and add the following lines:
GITREFER_TOKEN=<your_github_personal_access_token>
GITREFER_REPO=<owner_name/repository_name>
GITREFER_GEMINI_API_KEY=<your_google_ai_studio_api_key>For example,
GITREFER_TOKEN=abcdefgh1234567890
GITREFER_REPO=nken-eccs/PyGitrefer
GITREFER_GEMINI_API_KEY=1234567890abcdefghWarning
Keep your .env file secure and never share it publicly. It contains sensitive information that could compromise your GitHub account.
PyGitrefer will try to load these environment variables when you run the commands. It will search for the .env file in the current working directory or higher directories. If these environment variables are not set, you will be prompted to enter them manually.
Here's a breakdown of the commands you can use with PyGitrefer:
-
List All References:
gitrefer list
-
Show Reference Details:
gitrefer show <ID>
-
Show Raw Metadata of a Reference:
gitrefer raw <ID>
-
Show Directory Structure of the References Folder:
gitrefer tree
-
Add Reference from a Single DOI:
gitrefer add_doi <DOI>
-
Add Reference from Multiple DOIs Listed in a Text File:
gitrefer add_doi_from_file <path/to/file>
-
Add Reference from PDF (if a directory path is given, all PDFs in the directory will be added):
gitrefer add_pdf <path/to/pdf> or <path/to/directory>
-
Add Reference Manually:
gitrefer add_manual
-
Find New References:
gitrefer find_new
-
Update Reference:
gitrefer update <old_ID> [<new_ID>] - Delete Reference:
gitrefer delete <ID>- Add Tag to Reference:
gitrefer add_tag <ID> <tag>- Remove Tag from Reference:
gitrefer remove_tag <ID> <tag>- Add File to Reference:
gitrefer add_file <ID> <path/to/file>- Delete File from Reference:
gitrefer delete_file <ID> <filename>- Export References in a Specific Format:
gitrefer export <format> [-t <tag>] ...- Reset References:
gitrefer reset- Collaboration Made Easy: Work seamlessly with colleagues on shared research projects.
- Version Control: Track changes to your references over time, ensuring data integrity.
- Organization and Efficiency: Keep your references neatly organized and easily accessible from anywhere.
- Integration with GitHub: Leverage the familiar and powerful platform of GitHub.
Here are some exciting features I plan to add in the future:
- AI-Powered Reference Search: Use AI to search for new references that match your research interests, based on your existing bibliography. Github Actions may be used to automate this process.
- Custom Citation Styles: Generate citations in any format you need, with customizable templates.
Finally, I'm planning to create a GUI interface (Gitrefer) to make it even easier to manage your references.
If you have any feature requests or suggestions, please feel free to open an issue on GitHub.
If you'd like to contribute to this project, please feel free to submit a pull request or open an issue on GitHub. I really appreciate your support and feedback!
This project is licensed under the MIT License. See the LICENSE file for details.
Happy referencing!
Let PyGitrefer be your trusted guide in the vast world of academic literature. 🚢🧭