From 4c8588b00206686fecb90999f5de138bfd691e3d Mon Sep 17 00:00:00 2001 From: yasmineBML Date: Wed, 11 Nov 2026 17:09:52 +0100 Subject: [PATCH 1/3] Merge duplicated Git integration pages --- .gitbook.yml | 1 + en/SUMMARY.md | 1 - en/collaborative-work/README.md | 7 ------ en/collaborative-work/git-integration.md | 11 ++++++++++ en/collaborative-work/gitintegration.md | 27 ------------------------ 5 files changed, 12 insertions(+), 35 deletions(-) delete mode 100644 en/collaborative-work/gitintegration.md diff --git a/.gitbook.yml b/.gitbook.yml index 9d6ae5ba1..eb0201f7b 100644 --- a/.gitbook.yml +++ b/.gitbook.yml @@ -10,6 +10,7 @@ redirects: en: ./README.md de: ./README.md advanced/saveactions: ./finding-sorting-and-cleaning-entries/saveactions.md + collaborative-work/gitintegration: ./collaborative-work/git-integration.md contributing/translatinggui: ./faqcontributing/how-to-translate-the-ui.md download: ./installation.md EntryEditor: ./advanced/entryeditor/README.md diff --git a/en/SUMMARY.md b/en/SUMMARY.md index c85953e85..fa3a8c0d5 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -46,7 +46,6 @@ * [Export](collaborative-work/export/README.md) * [Custom export filters](collaborative-work/export/customexports.md) * [Send as email](collaborative-work/send-as-email.md) - * [Share with Git and GitHub](collaborative-work/gitintegration.md) * [AI functionality](ai/README.md) * [How to enable and use AI features?](ai/how-to-enable-and-use-ai-features.md) * [AI providers and API keys](ai/ai-providers-and-api-keys.md) diff --git a/en/collaborative-work/README.md b/en/collaborative-work/README.md index 7005424e1..3c10ef18a 100644 --- a/en/collaborative-work/README.md +++ b/en/collaborative-work/README.md @@ -2,8 +2,6 @@ JabRef allows sharing both [Bib(La)TeX library](sharedbibfile.md) and [SQL database](sqldatabase/). It also has [built-in Git integration](git-integration.md) for versioning your library. You can also [export your library to a variety of formats](export/). -Jabref also supports sharing libraries with [Git and GitHub](gitintegration.md). - {% content-ref url="sharedbibfile.md" %} [sharedbibfile.md](sharedbibfile.md) {% endcontent-ref %} @@ -23,8 +21,3 @@ Jabref also supports sharing libraries with [Git and GitHub](gitintegration.md). {% content-ref url="send-as-email.md" %} [send-as-email.md](send-as-email.md) {% endcontent-ref %} - -{% content-ref url="gitintegration.md" %} -[gitintegration.md](gitintegration.md) -{% endcontent-ref %} - diff --git a/en/collaborative-work/git-integration.md b/en/collaborative-work/git-integration.md index 46853e9f4..c4320dfb0 100644 --- a/en/collaborative-work/git-integration.md +++ b/en/collaborative-work/git-integration.md @@ -33,6 +33,11 @@ If the library file is not yet inside a Git repository, committing prompts you t Choose **Initialize** to create the repository and commit, or **Do not initialize** to leave the folder untouched — for example if you intend to clone an existing repository into it yourself instead. +## Pulling and pushing + +* **Push** uploads your local commits to the remote repository. If the remote contains changes you do not have yet, pull first. +* **Pull** fetches the latest changes from the remote and merges them entry by entry (semantic merge). If you and a collaborator changed the same field, JabRef opens a dialog where you resolve the conflict. + ## Authenticating with a remote ### HTTPS (GitHub Personal Access Token) @@ -43,12 +48,16 @@ For HTTPS-based remotes (such as GitHub), configure a Personal Access Token unde * **PAT** (Personal Access Token) * **Persist PAT between sessions** — stores the token in your operating system's credential store between JabRef sessions (only available if your OS provides one). +To create a token, follow GitHub's guide on [creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) and select the **repo** scope. Copy the token right away, as GitHub shows it only once. + ### SSH SSH-based remotes work without any separate configuration inside JabRef: JabRef authenticates through your system's running SSH agent (`SSH_AUTH_SOCK` on Linux/macOS, or Pageant/the Windows OpenSSH agent on Windows) and your usual `~/.ssh/config` and known-hosts entries, the same way the `git` command line tool would. ## Sharing a library to GitHub +Before sharing, [create a repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository): JabRef needs its URL. + **File → Git → Share this library to GitHub** opens a dialog to publish a saved local library to a new or existing GitHub repository: * **GitHub Repository URL** @@ -57,6 +66,8 @@ SSH-based remotes work without any separate configuration inside JabRef: JabRef * **Check GitHub access** — verifies the token has push access to the repository. * **Remember Git settings** — reuses the entered credentials for later commits/pushes. +JabRef then initializes a local Git repository (if needed), adds the GitHub repository as a remote, and pushes your library to it. + You can also reopen this dialog for a library that is already shared and has an existing Git remote, for example to re-check your token's access or to pull remote changes. {% hint style="info" %} diff --git a/en/collaborative-work/gitintegration.md b/en/collaborative-work/gitintegration.md deleted file mode 100644 index 6eb544fdc..000000000 --- a/en/collaborative-work/gitintegration.md +++ /dev/null @@ -1,27 +0,0 @@ -# Sharing a Library Using GitHub - -Note: These Git features are currently only available in the **v6.0 beta** and not in the current standard download at the [JabRef home page](https://www.jabref.org). To access them, download -the [v6.0 beta](https://github.com/JabRef/jabref/releases/tag/v6.0-beta.1) version of JabRef or build from source. - -JabRef allows you to use Git and GitHub to share entries with others. You can also use these features for version control and collaboration. - -### Setting up GitHub sharing - -To set up sharing with Git, first ensure that the bibliography file is correctly saved. Then follow these steps: - -1. *Create a remote GitHub Repository*: To begin, create a GitHub repository to store your entries remotely. You will need a GitHub account for this step - see [Creating a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). -2. *Create a Personal Access Token (PAT)*: To create a Personal Access Token for your GitHub account, follow the steps at: [Creating a GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). When prompted on what accesses the token should have, select the 'repo' permission. Make sure to copy the token or save it somewhere, as required for step 3. -3. *Add your Git credentials*: Add your GitHub credentials into JabRef by visiting **File -> Preferences** and searching for 'Git'. You should see boxes to place both your username and the PAT you made in step 2. Come back here to change your credentials at any time. -4. *Share the repository to GitHub*: Choose **File → Git -> Share this library to GitHub**. Enter the GitHub repository URL from step 1. This will initialise a local Git repository, add the repository from step 1 as a remote, and push your entries to the remote repository. - -### Using Git Features - -Once you share your library to GitHub, you will be able to use Git features from the **File → Git** menu: - -- *Commit*: Records the latest version of your bibliography file in your local repository. -- *Push*: Updates the remote repository with the newest version of your local commits. There must be no conflicts with the content of the remote repository. If there are conflicts, consider pulling first. -- *Pull*: Pulls the latest changes from the remote repositories and performs a semantic merge. If there are conflicts (such as conflicting changes between you and a collaborator), it will open a conflict menu where you can merge your changes together. - -For more information on how these commands work, see the [Git documentation](https://git-scm.com/doc). - -Note that this procedure automatically shares all files in the **libraries** directory of your project. Because of this we recommend to check that folder does not contain unrelated files, or to use a .gitignore file to exclude files, before sharing. From 5677663fa613e82b8e091c33df0b4ab69d13f8a4 Mon Sep 17 00:00:00 2001 From: yasmineBML Date: Wed, 11 Nov 2026 17:45:17 +0100 Subject: [PATCH 2/3] Restore beta availability note and sharing warning --- en/collaborative-work/git-integration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/en/collaborative-work/git-integration.md b/en/collaborative-work/git-integration.md index c4320dfb0..19c0afde4 100644 --- a/en/collaborative-work/git-integration.md +++ b/en/collaborative-work/git-integration.md @@ -4,6 +4,10 @@ description: Version-control your library with Git directly from JabRef. # Git Integration +{% hint style="info" %} +These Git features are currently only available in the [v6.0 beta](https://github.com/JabRef/jabref/releases/tag/v6.0-beta.1) and not in the current standard download at the [JabRef home page](https://www.jabref.org). To access them, download the v6.0 beta version of JabRef or build it from source. +{% endhint %} + JabRef can track your `.bib` library with [Git](https://git-scm.com/) directly from the application — you need no external Git client for the everyday commit/push/pull workflow. Open **File → Git**, which offers: * **Commit** @@ -68,6 +72,10 @@ Before sharing, [create a repository on GitHub](https://docs.github.com/en/repos JabRef then initializes a local Git repository (if needed), adds the GitHub repository as a remote, and pushes your library to it. +{% hint style="warning" %} +Sharing commits and pushes all files in the library's folder, not only the library file. Before sharing, check that the folder contains no unrelated or private files, or exclude them with a `.gitignore` file. +{% endhint %} + You can also reopen this dialog for a library that is already shared and has an existing Git remote, for example to re-check your token's access or to pull remote changes. {% hint style="info" %} From 3643af39d3da4ea950d4fdf739a40fa9de183514 Mon Sep 17 00:00:00 2001 From: yasmineBML Date: Sat, 14 Nov 2026 16:40:42 +0100 Subject: [PATCH 3/3] Remove beta availability note --- en/collaborative-work/git-integration.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/en/collaborative-work/git-integration.md b/en/collaborative-work/git-integration.md index 19c0afde4..a0a612c3b 100644 --- a/en/collaborative-work/git-integration.md +++ b/en/collaborative-work/git-integration.md @@ -4,10 +4,6 @@ description: Version-control your library with Git directly from JabRef. # Git Integration -{% hint style="info" %} -These Git features are currently only available in the [v6.0 beta](https://github.com/JabRef/jabref/releases/tag/v6.0-beta.1) and not in the current standard download at the [JabRef home page](https://www.jabref.org). To access them, download the v6.0 beta version of JabRef or build it from source. -{% endhint %} - JabRef can track your `.bib` library with [Git](https://git-scm.com/) directly from the application — you need no external Git client for the everyday commit/push/pull workflow. Open **File → Git**, which offers: * **Commit**