Implement logic orchestration for Git Pull/Push operations #13518

wanling0000 · 2025-07-09T13:54:54Z

Final PR based on draft: JabRef#714

This PR implements the logic-layer orchestration for Git push and pull operations with semantic merging support. It enables JabRef to semantically merge .bib files when possible, avoiding manual conflict resolution for simple changes.

This is part of ongoing work to support full Git-based collaboration for .bib files. Further tests and UI integration are planned.

Steps to test

This PR implements the first part of Git sync support by enabling automatic semantic merges when there are no conflicts. The scenario is tested via TDD in GitSyncServiceTest, simulating the following steps:

Alice creates an initial commit and pushes it to the remote.
Bob clones the repo and modifies entry b, then pushes.
Alice modifies entry a, then pulls.
Since they changed different entries, we expect a clean merge without user intervention. The orchestrator is GitSyncService, and helper utilities and value objects are temporarily located in org.jabref.logic.git.util.

Documentation Supplement

🧩 Table: Git-related Class Responsibilities

Class	Responsibility
`GitSyncService`	Orchestrates Git operations (pull, merge, push). Handles conflict detection, semantic merging, and committing results.
`GitHandler`	Wrapper around JGit, provides high-level Git operations like fetch, commit, push, and branch management.

🔧 Key Methods in `GitSyncService`

Method	Purpose	Description
`fetchAndMerge(Path)`	Pulls and merges changes	Runs status checks, fetch, 3-way merge, conflict detection, and auto-commit. Invokes a UI conflict resolution strategy if needed.
`performSemanticMerge(...)`	Performs semantic 3-way merge	Compares base/local/remote `.bib` content semantically. Uses `SemanticMerger` and conflict resolution strategy.
`push(Path)`	Pushes local changes to remote	Based on sync status, decides whether to commit and push. Fails if unresolved conflicts exist.

📦 Package: `org.jabref.logic.git.io`

This package bridges Git and JabRef's BibTeX data model by handling read/write operations for .bib files at specific Git revisions.

Class	Responsibility
`GitBibParser`	Parses `.bib` content from a Git commit into a `BibDatabaseContext` using JabRef's parser.
`GitFileReader`	Reads raw `.bib` text from a specific Git commit.
`GitFileWriter`	Writes `BibDatabaseContext` content back to a `.bib` file after merge.
`GitRevisionLocator`	Locates `base`, `local`, and `remote` commits for 3-way merge.
`RevisionTriple`	Data structure that holds the result of locating `base`, `local`, and `remote` revisions.

📦 Package: `org.jabref.logic.git.status`

Handles detection of Git repository and file tracking/sync status. Used before pull/push to determine the correct operation.

Class	Responsibility
`GitStatusChecker`	Static utility to check Git status of a `.bib` file and return a snapshot.
`GitStatusSnapshot`	Immutable snapshot of a file's Git tracking/conflict/sync state.
`SyncStatus`	Enum representing sync state (e.g., `UP_TO_DATE`, `BEHIND`, `DIVERGED`, etc.).

📦 Package: `org.jabref.logic.git.conflicts`

Handles semantic conflict detection and resolution strategies during 3-way merge.

Class	Responsibility
`SemanticConflictDetector`	Detects entry-level conflicts between base/local/remote `BibDatabaseContext`s.
`ThreeWayEntryConflict`	Data structure representing a single entry-level 3-way conflict.
`GitConflictResolverStrategy`	Interface for resolving conflicts — supports GUI/CLI strategies.
`CliConflictResolverStrategy`	CLI implementation (planned for JabKit, not yet integrated). GUI is currently prioritized.

Conflict Resolution Flow:

Detect conflicts with SemanticConflictDetector.
If conflicts exist, invoke a GitConflictResolverStrategy:
- In GUI: use GuiConflictResolverStrategy
- In future CLI: use CliConflictResolverStrategy
Apply merge plan if resolution succeeds.

📦 Package: `org.jabref.logic.git.merge`

Executes semantic 3-way merge operations on .bib files, including building merge plans and applying field-level changes.

Class	Responsibility
`MergePlan`	Represents semantic changes from base → remote to be applied to local.
`SemanticMerger`	Applies a `MergePlan` to a local `BibDatabaseContext`.
`GitSemanticMergeExecutor`	Interface defining a `performSemanticMerge()` contract.
`GitSemanticMergeExecutorImpl`	Default implementation of the above; invokes detector and merger.
`GitMergeUtil`	Utility class for low-level field and entry merging.

💡 GUI Module Integration Note

GUI dependencies are temporarily introduced to reuse the existing MergeEntriesDialog for conflict resolution.
This is injected via GitConflictResolverStrategy to keep the dependency direction correct (logic → gui).
A major UI refactor is WIP.

Class	Responsibility
`GuiConflictResolverStrategy`	GUI-based conflict resolution strategy. Reuses `MergeEntriesDialog` to let users manually resolve semantic conflicts in `BibEntry`s.

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
[/] Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
Tests created for changes (if applicable)
Manually tested changed features in running JabRef (always required)
[/] Screenshots added in PR description (if change is visible to the user)
Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

jabgui/src/main/java/org/jabref/gui/autosaveandbackup/BackupManager.java

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java

subhramit · 2025-07-09T17:18:23Z

jabgui/src/main/java/org/jabref/gui/LibraryTabContainer.java

@@ -27,7 +27,7 @@ public interface LibraryTabContainer {
     * Closes a designated libraryTab
     *
     * @param tab to be closed.
-     * @return true if closing the tab was successful
+     * @return true if closing the tab was isSuccessful


IntelliJ probably replaced this

Suggested change

* @return true if closing the tab was isSuccessful

* @return true if closing the tab was successful

…esolver interface to the logic module) JabRef#12350

…itMergeUtil tests JabRef#12350

…ort-init

…abRef#12350

…remote main branch exists JabRef#12350

…Ref#12350

trag-bot · 2025-07-15T17:41:13Z

jablib/src/main/java/org/jabref/logic/git/GitSyncService.java

+        // Status is BEHIND or DIVERGED
+        try (Git git = gitHandler.open()) {


Comment is trivial and can be derived from the code context. The status check above clearly indicates this is for BEHIND or DIVERGED cases.

trag-bot · 2025-07-15T17:43:35Z

jablib/src/test/java/org/jabref/logic/git/GitSyncServiceTest.java

+        // Debug hint: Show the created git graph on the command line
+        //   git log --graph --oneline --decorate --all --reflog


Commented code should be removed as per project guidelines. Git history should be used instead of keeping debug hints in comments.

Will remove in the end

… main branch JabRef#12350

…jabref into clean-gsoc-git-support-init

trag-bot · 2025-07-15T22:49:27Z

jablib/src/test/java/org/jabref/logic/git/GitSyncServiceTest.java

+     * 3. Alice update a → pull
+     */
+    @BeforeEach
+    void aliceBobSimple(@TempDir Path tempDir) throws Exception {


Method name contains typo in comment 'alieBobSetting' vs actual name 'aliceBobSimple', violating consistent and correct naming conventions in code.

jabref-machine · 2025-07-16T13:33:11Z

JUnit tests of jablib are failing. You can see which checks are failing by locating the box "Some checks were not successful" on the pull request page. To see the test output, locate "Tests / Unit tests (pull_request)" and click on it.

You can then run these tests in IntelliJ to reproduce the failing tests locally. We offer a quick test running howto in the section Final build system checks in our setup guide.

koppor · 2025-07-16T13:58:42Z

jablib/src/test/java/org/jabref/logic/git/GitSyncServiceTest.java

+import static org.mockito.Mockito.when;
+
+class GitSyncServiceTest {
+    private Git git;


Maybe name this aliceGit to be consistent with @BeforeEach

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/autosaveandbackup/BackupManager.java Outdated Show resolved Hide resolved

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java Outdated Show resolved Hide resolved

trag-bot bot reviewed Jul 9, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/desktop/os/Linux.java Outdated Show resolved Hide resolved

koppor added component: git project: gsoc labels Jul 9, 2025

subhramit reviewed Jul 9, 2025

View reviewed changes

subhramit mentioned this pull request Jul 9, 2025

WIP: GSoC Git Support - Support semantic pull merge without conflicts JabRef/jabref-koppor#714

Closed

4 tasks

wanling0000 added 9 commits July 14, 2025 01:50

init: add basic test case for git sync service

43ca5f7

feat(git): Add SemanticMerger MVP JabRef#12350

7fa3b86

feat(git): Implement normal sync loop without conflicts JabRef#12350

6233df9

chore(git): Apply review suggestions JabRef#12350

8d3fa2b

chore(git): Fix CI-related issues JabRef#12350

269473d

chore(git): Add push test + Fix failing unit test JabRef#12350

ac66eed

chore(git): Fix variable names + refactoring (moving the GitConflictR…

69575b5

…esolver interface to the logic module) JabRef#12350

refactor(git): Apply strategy pattern for conflict resolution + add G…

3fc49c3

…itMergeUtil tests JabRef#12350

fix: Repair failing unit tests and CI integration tests JabRef#12350

32c30a0

wanling0000 force-pushed the clean-gsoc-git-support-init branch from 8302ebc to 32c30a0 Compare July 14, 2025 00:54

wanling0000 added 5 commits July 14, 2025 02:09

Fix submodules

f8250d1

Merge remote-tracking branch 'upstream/main' into clean-gsoc-git-supp…

477cfae

…ort-init

test: Try to fix GitHandlerTest by ensuring remote main branch exists J…

61a19b8

…abRef#12350

test: Try to fix GitSyncServiceTest/GitStatusCheckerTest by ensuring …

7e36b2e

…remote main branch exists JabRef#12350

test: Try to fix GitSyncServiceTest by explicitly pushing refspec Jab…

cf60c02

…Ref#12350

trag-bot bot reviewed Jul 15, 2025

View reviewed changes

wanling0000 and others added 4 commits July 15, 2025 18:56

Merge branch 'main' into clean-gsoc-git-support-init

bf05ce9

test: Try to fix GitSyncServiceTest by explicitly checking out to the…

5799483

… main branch JabRef#12350

Merge branch 'clean-gsoc-git-support-init' of github.com:wanling0000/…

36e7d95

…jabref into clean-gsoc-git-support-init

test: Try to fix GitSyncServiceTest JabRef#12350

9107ddf

trag-bot bot reviewed Jul 15, 2025

View reviewed changes

Change exception logging

0ea08f1

Merge branch 'main' into clean-gsoc-git-support-init

bd2a738

koppor reviewed Jul 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Implement logic orchestration for Git Pull/Push operations #13518

Implement logic orchestration for Git Pull/Push operations #13518

Uh oh!

wanling0000 commented Jul 9, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

subhramit Jul 9, 2025

Uh oh!

trag-bot bot Jul 15, 2025

Uh oh!

trag-bot bot Jul 15, 2025

Uh oh!

wanling0000 Jul 15, 2025

Uh oh!

trag-bot bot Jul 15, 2025

Uh oh!

jabref-machine commented Jul 16, 2025

Uh oh!

koppor Jul 16, 2025

Uh oh!

Uh oh!

	* @return true if closing the tab was isSuccessful
	* @return true if closing the tab was successful

		// Status is BEHIND or DIVERGED
		try (Git git = gitHandler.open()) {

		// Debug hint: Show the created git graph on the command line
		// git log --graph --oneline --decorate --all --reflog

Uh oh!

Implement logic orchestration for Git Pull/Push operations #13518

Are you sure you want to change the base?

Implement logic orchestration for Git Pull/Push operations #13518

Uh oh!

Conversation

wanling0000 commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps to test

Documentation Supplement

🧩 Table: Git-related Class Responsibilities

🔧 Key Methods in GitSyncService

📦 Package: org.jabref.logic.git.io

📦 Package: org.jabref.logic.git.status

📦 Package: org.jabref.logic.git.conflicts

📦 Package: org.jabref.logic.git.merge

💡 GUI Module Integration Note

Mandatory checks

Uh oh!

Uh oh!

Uh oh!

Uh oh!

subhramit Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

wanling0000 Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

jabref-machine commented Jul 16, 2025

Uh oh!

koppor Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wanling0000 commented Jul 9, 2025 •

edited

Loading

🔧 Key Methods in `GitSyncService`

📦 Package: `org.jabref.logic.git.io`

📦 Package: `org.jabref.logic.git.status`

📦 Package: `org.jabref.logic.git.conflicts`

📦 Package: `org.jabref.logic.git.merge`