Verified Owner
Top Description Fields Constructors Methods
org.jabref.logic.git

public Class GitHandler

extends Object
Class Inheritance
Known Direct Subclasses
org.jabref.logic.git.SlrGitHandler
Imports
java.io.File, .IOException, .InputStream, java.net.URISyntaxException, java.nio.file.Files, .LinkOption, .Path, java.util.List, .Optional, .Set, org.jabref.logic.JabRefException, org.jabref.logic.git.preferences.GitPreferences, org.jabref.logic.l10n.Localization, org.jabref.logic.util.strings.StringUtil, org.eclipse.jgit.api.AddCommand, .FetchCommand, .Git, .PullCommand, .PushCommand, .RmCommand, .Status, org.eclipse.jgit.api.errors.GitAPIException, .JGitInternalException, .TransportException, org.eclipse.jgit.dircache.DirCache, org.eclipse.jgit.errors.NoRemoteRepositoryException, org.eclipse.jgit.lib.Constants, .Ref, .Repository, .StoredConfig, org.eclipse.jgit.merge.MergeStrategy, org.eclipse.jgit.revwalk.RevCommit, org.eclipse.jgit.transport.CredentialsProvider, .PushResult, .RefSpec, .RemoteRefUpdate, .URIish, .UsernamePasswordCredentialsProvider, org.eclipse.jgit.util.FileUtils, org.jspecify.annotations.NonNull, org.slf4j.Logger, .LoggerFactory
This class handles the updating of the local and remote git repository that is located at the repository path This provides an easy-to-use interface to manage a git repository

Field Summary

Modifier and TypeField and Description
private final GitPreferences
gitPreferences

private static final Logger
LOGGER

pack-priv final Path
repositoryPath

pack-priv final File
repositoryPathAsFile

Constructor Summary

AccessConstructor and Description
public
GitHandler(Path
The root of the initialized git repository
repositoryPath, GitPreferences gitPreferences)

Initialize the handler for the given repository

Method Summary

Modifier and TypeMethod and Description
public void
checkoutBranch(String
Name of the branch to check out
branchToCheckout)

Checkout the branch with the specified name, if it does not exist create it

private void
copyGitIgnoreIfAbsent()

public boolean

Returns:

true if a commit was created, false if the file was unchanged
createCommitForFileOnCurrentBranch(Path fileToCommit, String commitMessage)

Commits fileToCommit on the current branch, staging nothing else.

public boolean

Returns:

Returns true if a new commit was created. This is the case if the repository was not clean on method invocation
createCommitOnCurrentBranch(String commitMessage, boolean
Whether to amend to the last commit (true), or not (false)
amend)

Creates a commit on the currently checked out branch

private static Optional<String>
currentRemoteUrl(Repository repo)

public void
fastForwardTo(RevCommit remote)

Fast-forward only to <remote> (when local is strictly behind).

public void
fetchOnCurrentBranch()

public static Optional<Path>

Returns:

an optional containing the path to the Git repository root if found
findRepositoryRoot(Path
the file or directory path that is assumed to be located inside a Git repository
anyPathInsideRepo)

Try to locate the Git repository root by walking up the directory tree starting from the given path.

public static Optional<GitHandler>
fromAnyPath(Path anyPathInsideRepo, GitPreferences gitPreferences)

public Optional<CredentialsProvider>
getCredentialsProvider()

public String
getCurrentlyCheckedOutBranch()

private static String
getLocalizedPushRejectionMessage(RemoteRefUpdate update, String remoteMessage)

pack-priv Optional<Ref>
getRefForBranch(String branchName)

Returns the reference of the specified branch If it does not exist returns an empty optional

public File
getRepositoryPathAsFile()

public boolean
hasRemote(String remoteName)

public synchronized void
initAndCommit(@NonNull Path fileToCommit)

Creates the repository and commits fileToCommit together with the generated .gitignore.

public void
initIfNeeded()

pack-priv boolean
isGitRepository()

Returns true if the given path points to a directory that is a git repository (contains a .git folder)

public void
mergeBranches(String
the name of the branch that is merged into
targetBranch, String
the name of the branch that gets merged
sourceBranch, MergeStrategy mergeStrategy)

Merges the source branch into the target branch

public Git
open()

public void
pullOnCurrentBranch()

Pulls from the current branch’s upstream.

public void
pushCommitsToRemoteRepository()

Pushes all commits made to the branch that is tracked by the currently checked out branch.

public void
pushCurrentBranchCreatingUpstream()

private String
relativizeToRepository(Path file)

The Git index always uses forward slashes, independent of the platform.

private static boolean
requiresCredentialsForUrl(String url)

public static @NonNull Path
resolveToRealPath(@NonNull Path path)

Resolves symlinks so repository detection and repository-relative paths refer to the real file.

pack-priv void
setupGitIgnore()

private static void
verifyPushResults(Iterable<PushResult> pushResults)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

gitPreferencesback to summary
private final GitPreferences gitPreferences
LOGGERback to summary
private static final Logger LOGGER
repositoryPathback to summary
pack-priv final Path repositoryPath
repositoryPathAsFileback to summary
pack-priv final File repositoryPathAsFile

Constructor Detail

GitHandlerback to summary
public GitHandler(Path repositoryPath, GitPreferences gitPreferences)

Initialize the handler for the given repository

Parameters
repositoryPath:Path

The root of the initialized git repository

Method Detail

checkoutBranchback to summary
public void checkoutBranch(String branchToCheckout) throws IOException, GitAPIException

Checkout the branch with the specified name, if it does not exist create it

Parameters
branchToCheckout:String

Name of the branch to check out

copyGitIgnoreIfAbsentback to summary
private void copyGitIgnoreIfAbsent() throws IOException
createCommitForFileOnCurrentBranchback to summary
public boolean createCommitForFileOnCurrentBranch(Path fileToCommit, String commitMessage) throws IOException, GitAPIException

Commits fileToCommit on the current branch, staging nothing else.

Unlike createCommitOnCurrentBranch(String, boolean), which stages the whole working tree.

Returns:boolean

true if a commit was created, false if the file was unchanged

createCommitOnCurrentBranchback to summary
public boolean createCommitOnCurrentBranch(String commitMessage, boolean amend) throws IOException, GitAPIException

Creates a commit on the currently checked out branch

Parameters
amend:boolean

Whether to amend to the last commit (true), or not (false)

Returns:boolean

Returns true if a new commit was created. This is the case if the repository was not clean on method invocation

currentRemoteUrlback to summary
private static Optional<String> currentRemoteUrl(Repository repo)
fastForwardToback to summary
public void fastForwardTo(RevCommit remote) throws IOException, GitAPIException

Fast-forward only to (when local is strictly behind). Equivalent to: git merge --ff-only <remote>

fetchOnCurrentBranchback to summary
public void fetchOnCurrentBranch() throws JabRefException
findRepositoryRootback to summary
public static Optional<Path> findRepositoryRoot(Path anyPathInsideRepo)

Try to locate the Git repository root by walking up the directory tree starting from the given path.

If a directory containing a .git folder is found, return that path.

Parameters
anyPathInsideRepo:Path

the file or directory path that is assumed to be located inside a Git repository

Returns:Optional<Path>

an optional containing the path to the Git repository root if found

fromAnyPathback to summary
public static Optional<GitHandler> fromAnyPath(Path anyPathInsideRepo, GitPreferences gitPreferences)
getCredentialsProviderback to summary
public Optional<CredentialsProvider> getCredentialsProvider()
getCurrentlyCheckedOutBranchback to summary
public String getCurrentlyCheckedOutBranch() throws IOException
getLocalizedPushRejectionMessageback to summary
private static String getLocalizedPushRejectionMessage(RemoteRefUpdate update, String remoteMessage)
getRefForBranchback to summary
pack-priv Optional<Ref> getRefForBranch(String branchName) throws GitAPIException, IOException

Returns the reference of the specified branch If it does not exist returns an empty optional

getRepositoryPathAsFileback to summary
public File getRepositoryPathAsFile()
hasRemoteback to summary
public boolean hasRemote(String remoteName)
initAndCommitback to summary
public synchronized void initAndCommit(@NonNull Path fileToCommit) throws IOException, GitAPIException, JabRefException

Creates the repository and commits fileToCommit together with the generated .gitignore. Unlike initIfNeeded() this stages nothing else, so unrelated files in the directory (PDFs, notes, other libraries) stay untracked until the user adds them deliberately.

Fails with a JabRefException if there already is a repository, or if the file cannot be staged — an ignore rule excludes it from git add silently. Everything this call created is removed again on failure, so the user can fix the cause and retry, or clone into the directory instead.

synchronized so that concurrent invocations (the GUI submits this as a background task) cannot interleave: the rollback below may only ever delete a .git directory this invocation created, which the entry check guarantees while the lock is held. The registry hands out one handler per repository path, so the lock covers all in-process callers.

initIfNeededback to summary
public void initIfNeeded()
isGitRepositoryback to summary
pack-priv boolean isGitRepository()

Returns true if the given path points to a directory that is a git repository (contains a .git folder)

mergeBranchesback to summary
public void mergeBranches(String targetBranch, String sourceBranch, MergeStrategy mergeStrategy) throws IOException, GitAPIException

Merges the source branch into the target branch

Parameters
targetBranch:String

the name of the branch that is merged into

sourceBranch:String

the name of the branch that gets merged

openback to summary
public Git open() throws IOException
pullOnCurrentBranchback to summary
public void pullOnCurrentBranch() throws IOException

Pulls from the current branch’s upstream. If no remote is configured, silently performs local merge. This ensures SLR repositories without remotes still initialize correctly.

pushCommitsToRemoteRepositoryback to summary
public void pushCommitsToRemoteRepository() throws IOException, GitAPIException, JabRefException

Pushes all commits made to the branch that is tracked by the currently checked out branch.

pushCurrentBranchCreatingUpstreamback to summary
public void pushCurrentBranchCreatingUpstream() throws IOException, GitAPIException, JabRefException
relativizeToRepositoryback to summary
private String relativizeToRepository(Path file)

The Git index always uses forward slashes, independent of the platform.

requiresCredentialsForUrlback to summary
private static boolean requiresCredentialsForUrl(String url)
resolveToRealPathback to summary
public static @NonNull Path resolveToRealPath(@NonNull Path path)

Resolves symlinks so repository detection and repository-relative paths refer to the real file. Falls back to the lexical absolute path when resolution fails (e.g. the file vanished meanwhile).

setupGitIgnoreback to summary
pack-priv void setupGitIgnore()
verifyPushResultsback to summary
private static void verifyPushResults(Iterable<PushResult> pushResults) throws JabRefException