Edit online

Git Client Add-on

The Git Client add-on integrates a full Git client into Oxygen, so that you can commit, push, pull, branch, and resolve conflicts without leaving the editor.

Compatibility:
This add-on is compatible with Oxygen XML Editor, Oxygen XML Author, Oxygen XML Developer, and Oxygen JSON Editor.

After you install it, the Git Client adds three dedicated views, a top-level Git menu, several preferences pages, and contextual Git actions in other views and editors.

The three dedicated views are:

  • Git Staging - This is where you review changes, stage them, commit, push, and pull.
  • Git History - It displays the commit graph so that you can inspect and compare revisions.
  • Git Branch Manager - This view lists your local and remote branches so that you can manage them.

The topics that follow are arranged in the order you will usually need them: install the add-on, get oriented, connect to a server, and set up a repository, then review and commit your work, synchronize with the remote, resolve conflicts, work with branches and tags, and review history. Advanced workflows, configuration, a full interface and actions reference, and troubleshooting come at the end for reference purposes.

Edit online

Install the Git Client

Add the Git Client to Oxygen in one of two ways, then restart to begin using it.

There are two ways to install the Git Client:

After you restart, the three Git views (Staging, History, Branch Manager), the Git menu, and the contextual Git actions become available.

Edit online

Install from the Add-ons Store

Drag an Install button into the editor to add the Git Client in one step.

You must be running Oxygen 26.1 or newer.

  1. Drag the following Install button into Oxygen.

    You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:

    Install

  2. Confirm the installation and restart Oxygen when prompted.
Edit online

Install Manually from a File or Update Site

Install the Git Client from the update site, or from a downloaded package when the site cannot be reached.

  1. Go to Help > Install new add-ons.
  2. In the Show add-ons from field, enter https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml.
    Note:
    If you have trouble reaching the update site, download the add-on package, unzip it, and use Browse for local files to select the addon.xml file instead.
  3. Select the Git Client add-on, then select Next.
  4. Read the license agreement and accept it.
  5. Restart Oxygen to finish the installation.
Edit online

Tour the Git Client Interface

The Git Client spreads its work across three views, a menu, and contextual actions.

Table 1. Where Git Work Happens
Location Use it to
Git Staging view Review changes, stage them, commit, and push or pull. This is your day-to-day workspace.
Git History view Explore the commit graph, inspect a commit, compare revisions, and see which files a commit changed.
Git Branch Manager view Browse local and remote branches, and switch, create, merge, or delete them.
Git menu Run repository-level commands (clone, open, push, pull, fetch), and open Git Client preferences.
Contextual Git actions Work with Git directly from the Project view, the DITA Maps Manager, and the editor.
Preferences Configure how the Git Client behaves, including validation and AI options.

To open any of the three views, use Window > Show View, or open the Git Staging view and use its toolbar to reach the other two.

Edit online

Connect to a Git Server

The Git Client connects to GitHub, GitLab, Bitbucket, and other servers over HTTPS or SSH, and remembers your credentials per server.

When you push, pull, fetch, or clone from a private repository, the server asks for credentials. The Git Client supports two connection types:

  • HTTPS - You authenticate with a username and a personal access token (or a password, where the server still allows it).
  • SSH - You authenticate with an SSH key, optionally through an SSH agent.

The Git Client stores one set of credentials per server, encrypted in the Oxygen options. If no credentials are stored, it prompts you the first time they are needed. To change accounts or clear stored credentials, see Manage Credentials.

Edit online

Authenticate over HTTPS

Sign in to an HTTPS remote with a personal access token, or a username and password.

The first time an operation needs credentials for an HTTPS remote, the Git Client opens a login dialog box. It stores what you enter and reuses it for that server.

  1. Choose the authentication type.
    • Personal access token - Recommended, and required by GitHub and for any account with two-factor authentication enabled.
    • Basic authentication - A username and password, where the server still allows it.
  2. Enter your credentials and confirm.
    Note:
    GitHub no longer accepts account passwords for Git operations. Generate a personal access token and use it instead. For Bitbucket, create an API token with the required scopes and use it as the password with your Bitbucket username. See Authentication Fails (GitHub, GitLab, Bitbucket) if a sign-in is rejected.

The Git Client stores the credentials for that server and stops prompting. To review or remove them later, see Manage Credentials.

Edit online

Authenticate over SSH

Connect to an SSH remote using your SSH keys, optionally through an SSH agent.

For SSH remotes, the Git Client authenticates with your SSH key. It can use a running SSH agent so you do not retype your passphrase, and it supports ssh-agent forwarding.

  1. Open the SSH Connections preferences page.
  2. Select Use SSH Agent to authenticate through an agent.

    On Windows, choose the agent to use:

    • Win32-OpenSSH (default)
    • Pageant

    On Linux, macOS, and BSD, the Git Client communicates with the agent through the standard Unix domain socket.

The Git Client uses the keys held by the agent for SSH operations. If a key is protected by a passphrase and no agent is available, it prompts you for the passphrase.

Edit online

Manage Credentials

Review, update, or remove the credentials the Git Client has stored for your Git servers.

The Git Client stores one credential set per server. You can see what is stored, remove individual entries, or clear everything.

  1. Open the Git Client preferences page, then select the Credentials page.

    The Credentials page lists every stored HTTP or token credential with its Host, Type (personal access token or basic authentication), and Username.

    Figure 1. Credentials Preferences Page
  2. Select one or more entries, then select Remove.

    Changes are applied only when you select OK or Apply, so that you can cancel safely.

The next time an operation needs credentials for a removed server, the Git Client prompts you again. When you re-authenticate, the login dialog box pre-selects the stored authentication type and fills in the username for basic authentication.

Tip:
To remove several servers at once, select their rows on the Credentials page and select Remove. To clear a stored SSH passphrase, use the Clear button on the SSH Connections preferences page.
Edit online

Set Up a Repository

Start working with a repository by cloning a remote one, putting your project under version control, or opening a repository you already have.

The Git Client always works with one active working copy, the local repository it currently operates on. There are three ways to get one:

Edit online

Clone a Repository

Copy a remote repository to your machine so that you can start working with it.

Cloning downloads a full copy of a remote repository and sets it as your current working copy. If the repository uses submodules, the Git Client initializes and clones them for you.

  1. On the Git Staging toolbar, open the Vertical Ellipsis menu and select Clone repository....
  2. Fill in the Clone repository dialog box.
    Repository URL
    The URL of the remote repository to clone.
    Checkout branch
    The branch to check out. Leave this empty to check out the default branch.
    Destination path
    The local folder for the clone. When you enter a URL, the Git Client suggests a folder named after the repository.
    Figure 2. Clone Repository Dialog Box

The Git Client clones the repository and sets it as the current working copy.

Edit online

Create a Repository from Your Project

Put an existing project under version control by turning its folder into a Git repository.

Create the repository in one of these ways:
  • From the Vertical Ellipsis menu, select Create repository in project.
  • In the Project view, right-click a folder that is not yet a repository and select Create repository here.
Note:
If Ask user to create new repository is enabled, the Git Client also offers to create one when you open a project folder that is not under version control.

The folder becomes a local Git repository and the current working copy. It has no remote yet, so the Git Client prompts you for a remote URL the first time you push or pull.

Edit online

Open an Existing Working Copy

Point the Git Client at a Git repository that is already on your machine.

  1. In the Git Staging view, open the Working copy drop-down.
  2. Select a recently used working copy, or choose Browse to locate a Git repository folder on disk.

The selected repository becomes the current working copy.

Note:
When you open a working copy, the Git Client checks for local branches whose remote branch was deleted and offers to remove them. You can turn this check off in the Git Client Preferences. See Repository Shows as Outdated for details.
Edit online

Review, Stage, and Commit Changes

Review local edits, set aside work when needed, stage the changes you want, and commit them to your local repository.

Use the Git Staging view to inspect and manage local changes before you commit. Modified files appear in the Unstaged files area, and staging files moves them into the Staged files area, ready to commit. From the same view, you can stash changes if you need a clean working copy before you are ready to commit.

  1. Review your changes in the Unstaged files area.

    Double-click a file to open it in the compare editor and see exactly what changed. See Compare Changes Before Committing.

  2. Stage the changes you want to commit.

    Select files and use Stage selected, or use Stage all. To move a file back, use Unstage selected or Unstage all.

  3. Enter a message in the Commit message area that describes the staged changes.
    Tip:
    You can generate, reuse, or amend the message using the commit-area options. See Write Commit Messages with AI.
  4. Select Commit.

The Git Client records the staged changes as a commit in your local repository. Push the changes when you are ready to share them.

Edit online

Compare Changes Before Committing

See exactly what changed in a file (including images) before you stage or commit.

In the Unstaged files or Staged files area, double-click the file.

The compare editor opens and highlights the differences between your version and the last committed version. Because a newly added file has no version in the last commit, double-clicking it opens the file instead. The exception is a file that you staged and then edited again, because the staged row has its own content to display.

Each pane is labeled with the version it displays. For an unstaged file, the comparison is between Working copy and Last commit, or between Working copy and Staged if the same file also has staged changes. For a staged file, the comparison is between Staged and Last commit.

When the file is one that this working copy adds, the second pane is empty and is labeled Last commit - file did not exist yet.

A staged row always shows what it contributes to the next commit. Therefore, for a file that you edited again after staging it, use the Open action to open the staged version in read-only mode. Use Open working copy version to open the editable file from the working copy. A staged row on the Uncommitted changes row in the Git History view shows and opens the same versions as in the Git Staging view.

Note:
For image files (PNG, JPEG, GIF, BMP, TIFF, and other raster formats), the Git Client opens a side-by-side image comparison, with the newer version on the left and the older version on the right. SVG files are treated as XML, so they open in the regular text comparison (where you can switch to Author mode to see them rendered).
Figure 3. Image Comparison
Edit online

Validate Before Commit and Push

Catch problems early by validating files before you commit and push them.

The Git Client can run validation automatically at two points. Both checks are on by default and are configured on the Git Client preferences page.

  1. To validate each file as you commit, keep Validate each file before committing selected.

    If problems are found, the commit stops and the Git pre-commit validation tab of the Results area lists them. Select Allow commit despite validation problems to be able to Commit anyway.

  2. To validate your project before you push, keep Validate all files from the project's "Main Files" folder before pushing selected.

    This requires Main Files support, a configured validation scenario, and a matching project with no uncommitted changes (the Git Client offers to stash them otherwise). Problems appear in the Git pre-push validation tab, then select Allow push despite validation problems to be able to Push anyway.

    Note:
    Because this can stash your changes internally, pre-push validation is refused if the working copy has a filesystem name collision. See Stash Changes.
Edit online

Stash Changes

Shelve your current changes so that you can switch context, then bring them back later.

A stash sets your uncommitted changes aside and returns the working copy to a clean state. Use it when you need to switch context, such as before switching branches, pulling remote changes, or starting another task before you are ready to commit. Your changes wait in the stash until you apply them again.

Note:
If your working copy has a file system name collision (for example, two files whose names differ only in letter case on a case-insensitive file system), stashing is refused, and so are the pull and pre-push operations that stash internally. Resolve the collision before you stash. See The Git Client Reports a Filesystem Name Collision.
  1. On the Git Staging toolbar, open the Stash drop-down and select Stash changes....

    To stash only part of your work, select the files in the Unstaged files or Staged files area, right-click, and select Stash selected files.... This stashes the complete change of each selected file (both its staged and unstaged parts) and reverts those files to their last committed state, leaving every other change in the working copy untouched. The Include untracked option controls whether selected untracked files are included. If it is off and your selection contains only untracked files, nothing is stashed. The action is unavailable when the selection contains conflicts.

    Warning:
    Because a partial stash is carried out in several steps, the Git Client first saves a full backup stash labeled Backup created while stashing selected files. If the operation fails partway, your working copy may be left partially modified. To recover, open the stashes dialog box, apply that backup stash, and then delete it.
  2. To bring a stash back, open the Stash drop-down and select List stashes....

    In the Stashes dialog box, Apply restores the selected stash, Delete removes it, and Delete all clears every stash. Select Delete stash after being applied to remove a stash automatically once it is applied. Applying a stash can produce conflicts, which you can resolve as described in Resolve Conflicts.

    Figure 4. Stashes Dialog Box
Edit online

Sign Your Commits

Sign commits with an SSH or GPG key when your environment is set up for it.

If your environment is configured for commit signing, the Git Client signs your commits with SSH or GPG keys. You do not need to do anything extra when you commit.

Configure GPG signing through the GNUPGHOME environment variable.

GPG support honors GNUPGHOME as the directory where your keys are stored. If it is not set, the Git Client uses %APPDATA%\gnupg on Windows and ~/.gnupg on other systems. The jgit.gpg.home Java system property takes precedence over GNUPGHOME if both are set.

Edit online

Write Commit Messages with AI

Generate a commit message using AI, reuse a previous one, or amend your last commit.

The toolbar above the Commit message area has options that help you write and reuse messages.

Use any of the commit-message options:
Generate commit message using AI
Drafts a message from the staged changes, using AI Positron. Customize how it writes messages in the AI preferences page.
Choose a previously used comment
Reuses a message from a recent commit.
Amend last commit
Adds the staged changes to your most recent local commit, or edits its message.
Automatically push changes to remote branch
Pushes the commit to the remote immediately after you commit.
Warning:
Avoid amending, rebasing, or resetting commits you have already pushed. These operations rewrite history, which disrupts anyone who has already pulled those commits.
Edit online

Exclude Files from Version Control

Keep generated files, local settings, and other clutter out of Git with a repository .gitignore or a global ignore file.

Ignore rules come in two scopes:
  • A .gitignore file that is located in the repository and shared with everyone.
  • A global ignore file that applies to all your repositories. Ignore actions are available for untracked files only.
  1. In the Unstaged files area, right-click an untracked file or folder and open the Ignore submenu.
  2. Choose what to ignore:
    Ignore this file
    Ignores the selected file.
    Ignore by extension
    Ignores every file with the same extension. Not available for dotfiles or files that have no extension.
    Ignore parent directory
    Ignores the folder that contains the selected file. Not available for files at the repository root.
    Ignore this directory
    Ignores the selected folder (for a folder selection).
    Ignore all files
    Ignores every file in the selected folder (for a folder selection).

    Each action adds the matching rule to the repository .gitignore file. You can select several untracked resources and ignore them together. The same Ignore submenu is also available on the Git History contextual menu, where it applies to a single untracked file.

To edit the rules directly, open the Vertical Ellipsis menu and choose Open project .gitignore or Open global ignore file.

Edit online

Synchronize with a Remote

Keep your local and remote repositories synchronized by pushing, pulling, and fetching.

Three operations move commits between your machine and the remote:

  • Push Commits sends your local commits to the remote.
  • Pull Changes brings the remote's commits into your local branch.
  • Fetch from Remotes downloads the remote's latest state without changing your working copy.
Edit online

Push Commits

Send your local commits to the remote repository so others can see them.

On the Git Staging toolbar, select Push.

The push is sent to the remote tracked by the current branch. To push to a different remote, use the Push to submenu in the Git menu or in the Vertical Ellipsis menu.

The Git Client sends your commits to the remote branch. If the branch exists only locally, it creates a matching remote branch and starts tracking it. If the repository has more than one remote, you are prompted to choose which one to publish the branch to.

If the push is rejected because your local branch is behind the remote, pull the remote changes first, then push again.

For the full explanation, see Push Is Rejected Because the Branch Is Behind.

Tip:
To keep two servers in sync with a single push, assign multiple push URLs to one remote with git remote set-url --add --push <remote> <url>. The Git Client pushes by remote name, so one Push action reaches every URL you added. This is one way to mirror a repository, which is a type of push-to-all-remotes action.
Edit online

Pull Changes

Bring the remote's commits into your local branch, by merging or rebasing.

Pulling files downloads the remote commits and integrates them into your current branch. You choose how they are integrated. See About Merge and Rebase if you are unsure which to pick.

On the Git Staging toolbar, open the Pull drop-down and choose how to integrate the changes.
  • Pull (merge) - Creates a merge commit if your branch and the remote have both moved on.
  • Pull (rebase) - Replays your local commits on top of the remote ones for a linear history.
  • Pull... - Pulls from a branch other than the one you are tracking.

The option you choose between Pull (merge) and Pull (rebase) becomes the default action on the toolbar button.

If the pull produces conflicts, resolve them before continuing. See Resolve Conflicts.

Note:
A pull may need to set your local changes aside before it integrates remote commits. The Git Client can stash those changes internally, but the operation is refused if the working copy has a file system name collision. To manually set aside changes before pulling, see Stash Changes.
Edit online

Fetch from Remotes

Download the latest commits and branch information from your remotes without changing your working copy.

Fetching updates your remote-tracking information (what the Git History and Git Branch Manager views show), so that you can see what is on the remote before you pull. It never merges or changes your files.

Start a fetch in one of these ways:
  • From the Git menu or the Vertical Ellipsis menu, select Fetch to fetch from all configured remotes.
  • In the Git Branch Manager view, right-click the Remote node to fetch all remotes, or a specific remote such as origin to fetch only that one.

A remote can be configured to download only some of its branches. Such a remote is marked (partial) in the Git Branch Manager view, and a local branch whose upstream is left out is marked (not fetched). To change what is downloaded, see Branch Tree.

The Git History and Git Branch Manager views update to reflect the latest remote state.

Edit online

About Merge and Rebase

Merge and rebase both combine two lines of work, but they keep the history differently.

When your branch and the branch you are integrating have both moved on, Git has to reconcile them. You have two strategies to choose from:

Merge
Joins the two histories with a merge commit. Your existing commits stay exactly as they were, and the merge commit records that the two lines came together. History is complete but not linear.
Rebase
Replays your local commits on top of the other branch, one by one, so the history stays linear, as if you had started your work from the latest state. Because it rewrites your commits, use it only on commits you have not shared yet.

Either strategy can produce conflicts, which you resolve the same way. See Resolve Conflicts.

Edit online

Resolve Conflicts

When the same lines change on two branches, Git needs your help to decide what to keep.

A conflict happens when a merge, rebase, cherry-pick, revert, or stash apply tries to combine two changes to the same part of a file. Git cannot decide which version to keep, so it pauses and asks you.

The Git Client marks each conflicting file in the Unstaged files area of the Git Staging view and keeps the operation in progress until you resolve every one. You have a few ways to do that:

  • Edit the file in the compare editor and choose what to keep, line by line.
  • Accept one whole side with Resolve Using "Mine" or Resolve Using "Theirs".
  • Let Oxygen AI Positron propose a resolution with Resolve with AI.

After a file is resolved, the Git Client stages it automatically. When every file is resolved, you can finish the operation. If you would rather back out, you can abort and return to the state before the operation started.

Edit online

Resolve a File Conflict

Resolve a conflicting file by editing it in the compare editor or by keeping one entire side.

Conflicting files appear in the Unstaged files area. Resolve each one, then finish the operation.

  1. Right-click the conflicting file and open the Resolve conflict submenu.
  2. Choose how to resolve the file.
    • Select Open in compare editor, edit the file so that it keeps the correct content, and then apply your changes. Each pane caption shows which side it represents, and you edit the pane marked → Resolved. The captions use the same terms as the Git History view for the commits involved (see Track and Finish an In-Progress Operation).
    • Select Resolve Using "Mine" to keep your version, or Resolve Using "Theirs" to keep the incoming version.
    • After editing a file manually, select Mark Resolved.

The Git Client stages each resolved file automatically. When all files are resolved, finish the operation (see Track and Finish an In-Progress Operation).

Tip:
Let Oxygen AI Positron propose a resolution with Resolve with AI. See Resolve Conflicts with AI.
Edit online

Resolve Conflicts with AI

Let AI Positron analyze a conflict and propose a resolution you can review and apply.

Important:
This feature requires the Oxygen AI Positron add-on.
  1. Right-click the conflicting file and select Resolve with AI.
    Note:
    This action works on text files only, so it is not offered for image or SVG conflicts. If the file is too large for the AI context window, the operation stops with an error rather than sending only part of the file.
    AI Positron analyzes the conflicting file and its common ancestor, then opens the AI Conflict Resolution window.
  2. Review the proposed resolution.

    The AI analysis pane explains, in plain language, what each side changed. Four comparison views let you inspect the proposal (Resolved vs Mine, Resolved vs Theirs, Resolved vs Conflicted, and Mine vs Theirs) where Mine is your version, Theirs is the incoming change, and Resolved is the AI proposal (always shown on the left). The resolved file is editable in each view, allowing you to fine-tune it (use Restore original AI suggestion to undo your edits).

    Note:
    During a rebase, these labels follow Git's own convention, which is the reverse of a merge: Mine is the branch you are rebasing onto (the new base), and Theirs is the commit being replayed (your own work). The AI explanation and the comparison views use this same orientation.
  3. Select Use Resolved.

The Git Client writes the resolution to your working copy and stages the file.

Edit online

Track and Finish an In-Progress Operation

See the status of a paused merge, rebase, cherry-pick, or revert, then abort, restart, or continue it.

When an operation pauses because of conflicts, the Git Client shows its current status. The Git Staging view labels the operation in progress (for example, Merging), and the Git History view marks the related commits with amber labels. Your current commit is labeled Start (Mine), and the incoming side is labeled according to the operation: Incoming (Theirs) for a merge, Cherry-picked (Theirs), or Reverted (Theirs). During a rebase, the commit being replayed is labeled Replayed, and that commit is your own work. A rebase reverses the sides, so your commit is the incoming one. The Uncommitted changes node is connected by a dashed gray line to its parent commit, or to both parents when a merge is in progress.

The compare editor uses the same labels. Each pane begins with the role of the side, followed by the branch when the commit is the tip of one, the date, the short revision, the author, and the first line of the commit message. The pane you resolve into adds → Resolved. For example, a merge compares Start (Mine) → Resolved with Incoming (Theirs), and a rebase compares Rebased onto → Resolved with Replayed. The window title shows the file name and the operation, for example Merge conflict in config.dita.

Figure 5. In-Progress Merge in the Git History View
  1. Resolve any conflicts the operation reported.
  2. Use the buttons in the conflict panel above the file list to finish or back out of the operation. The buttons depend on which operation is in progress:
    Merge in progress
    Abort Merge, Restart Merge
    Rebase in progress
    Abort Rebase, Continue Rebase
    Cherry-pick in progress
    Abort Cherry-pick
    Revert in progress
    Abort Revert
    • Abort - Restores the state from before the operation started.
    • Restart Merge - Reverts your working-copy changes so that you can try a different strategy.
    • Continue Rebase - Completes the rebase after every conflict is resolved.

    After every file is resolved, the panel shows Conflicts resolved and explains the remaining step in its tooltip. It stays visible until you commit, so these actions remain available.

Edit online

Work with Branches and Tags

Branches let you work on several things in parallel, and tags mark points in history worth remembering.

The Git Branch Manager view lists your Local and Remote branches, and the Branch drop-down in the Git Staging view always shows the current branch. From here you can switch, create, combine, and clean up branches, and create tags to mark releases or milestones.

Edit online

Switch to Another Branch

Change the current local branch from the Git Staging view or the Branch Manager.

Switch branches in either view:
  • In the Git Staging view, choose a branch from the Branch drop-down.
  • In the Git Branch Manager view, double-click a local branch.

If you have uncommitted changes, the Git Client offers to stash them or carry them to the other branch before switching. You can also cancel and commit first. To manually set aside changes before switching branches, see Stash Changes.

Edit online

Check Out a Branch

How to check out an existing branch, create a new one from a commit, or inspect a commit in a detached HEAD.

Check out from the Git History view, starting from a chosen commit.

  1. Right-click a commit in the Git History view and select Checkout to open the Checkout dialog box.

    Double-clicking a commit skips the dialog box when the choice is unambiguous. Double-click a commit row that has a single local branch to switch to that branch, or double-click a branch label to switch to that specific branch.

  2. Choose what to check out.
    • Switch to existing local branch - Checks out a branch that already points to the commit. This option appears only when one or more local branches point to the commit.
    • Create a new branch - Enter a Branch name and, optionally, set it to track a remote branch. The Git Client pre-fills a suggested name and tracking when possible.
    • Detached HEAD - Checks out the commit without a branch for a quick inspection.
    Figure 6. Checkout Dialog Box
  3. Click Checkout when finished configuring the dialog box. If uncommitted changes are present when you confirm the checkout, you are presented with actions to:
    • Stash changes - Stashes your uncommitted changes on the current branch for later use, then switches to the chosen branch.
    • Move changes - Switches to the chosen branch and carries your uncommitted changes with it.
    • Cancel - Aborts without switching.
    Notes:
    • An amber HEAD label marks the current commit while the repository is in detached HEAD mode. Any commits you create in this state are not on a branch, so create a branch before you switch away if you want to make them easier to distinguish.
    • To switch to an existing local branch from the Git Staging view or the Git Branch Manager view, see Switch to Another Branch.

The repository switches to the selected branch or commit. If you create a new branch, Git checks it out at the selected commit and applies the tracking configuration you selected. If you choose Detached HEAD, the repository remains in detached HEAD mode until you switch to or create a branch.

Edit online

Create a Branch

Branch from the current HEAD or from any commit in the history.

  1. Start a new branch in either view:
    • In the Git Branch Manager view, right-click a branch and select Create Branch.
    • In the Git History view, right-click the commit to branch from and select Create Branch.
  2. Enter a name for the branch.

    Leave Checkout branch selected to switch to the new branch, or clear it to create the branch without switching.

Edit online

Merge, Rebase, or Cherry-Pick

Bring work from another branch or commit into your current branch.

Choose the approach that fits your needs. See About Merge and Rebase for how merge and rebase differ.

Run the operation you need.
  • To combine a whole branch, right-click it in the Git Branch Manager view and select Merge or Squash Merge.
  • To replay your commits onto another commit, right-click the target commit in the Git History view and select Rebase..., then confirm. This replays all of the current branch's local commits onto that commit. It is not an interactive rebase.
    Note:
    If the current branch has already been pushed to a remote, you need to force push after the rebase because the branch history changed.
  • To copy a single commit onto your branch, right-click it in the Git History view and select Cherry-Pick.

If the operation produces conflicts, resolve them and finish it. See Track and Finish an In-Progress Operation. A rebase is blocked if there are unresolved conflicts or uncommitted changes that would be overwritten.

Warning:
Avoid amending, rebasing, or resetting commits you have already pushed. These operations rewrite history, which disrupts anyone who has already pulled those commits.
Edit online

Revert or Reset Commits

Undo commits, either by adding an inverse commit (revert) or by moving the branch pointer back (reset).

In the Git History view, right-click the commit and choose the desired action.
  • Revert Commit - Adds a new commit that undoes the selected one. This is safe for commits you have already shared, because it does not rewrite history.
  • Reset Branch to Commit - Moves the current branch back to the selected commit. Use this with care, and only on commits you have not shared.
Warning:
Avoid amending, rebasing, or resetting commits you have already pushed. These operations rewrite history, which disrupts anyone who has already pulled those commits.
Edit online

Create and Manage Tags

Tag a commit to mark a release or milestone, then push, check out, or delete the tags.

  1. To create a tag, right-click a commit in the Git History view and select Create Tag. New tags remain local until you push them.

    If the repository has more than one remote, the dialog box includes a Push to remote: option so that you can choose where to push the tag.

  2. To manage existing tags, open the Git menu and select Show tags....

    In the Tags dialog box, you can check out a tag, push a local-only tag to the remote, or delete a tag. The Pushed to column lists the remotes that already contain each tag.

    Figure 7. Tags Dialog Box
Edit online

Review History and Commits

Explore the commit graph, inspect what each commit changed, and trace a line back to the commit that last touched it.

The Git History view shows the commit graph, the details of any commit, and the files it changed. From there you can inspect and compare revisions, get a plain-language summary of a commit with AI, and see who last changed each line of a file.

Edit online

Inspect and Compare Commits

Review a single commit, compare a range of revisions, or compare your working copy against an earlier one.

  1. Inspect or compare commits in the Git History view.
    • Select one commit to see its Commit Details (bottom-left pane) and the Affected Resources it changed (bottom-right pane).
    • Select two or more commits (use Ctrl or Shift) to see the differences across that range.
    • Select the Uncommitted changes entry together with a revision to compare your working copy against that revision. This is available only when the working copy has uncommitted changes.

    Select any single commit to end a revision comparison.

    Figure 8. Comparing a Range of Revisions
  2. In the Affected Resources pane, right-click a file to open, compare, or reset a specific version.
Edit online

Explain a Commit with AI

Get a plain-language summary of the changes for one or more commits.

Important:
This feature requires the Oxygen AI Positron add-on.
In the Git History view, select one or more commits, right-click, and select Explain commit with AI.

The AI Positron view opens with a summary of the selected commits. Customize how it writes summaries on the AI preferences page.

Edit online

Show Blame

See who last changed each line of a file, and jump to the commit behind any line.

  1. Right-click a file (in the Unstaged files area, the editor, the Project view, or the DITA Maps Manager) and select Show Blame.

    The editor colors each line by the commit that last changed it. Clicking a line filters the Git History view to that file and selects its commit, so that you can see the full change.

  2. To turn the coloring off, select Hide Blame from the same contextual menu.

    The blame highlights are removed without closing the editor, and the Git History file filter is cleared so the panel shows the full repository history again.

Edit online

Advanced Workflows

Less-common repository structures and storage features the Git Client supports, including submodules, worktrees, and large files.

For specialized repository setups, the Git Client supports:

Edit online

Work with Submodules

The Git Client initializes, clones, and updates submodules for you as you work.

A submodule is a repository nested inside another. The Git Client handles most of the bookkeeping automatically:

  • Cloning a repository initializes and clones its submodules.
  • Pulling updates the submodules, when Update all submodules after pulling changes from the remote repository is selected in the preferences.
  • Checking out a branch checks out its submodules at the recorded commit.
To open a submodule as the working copy, open the Git menu and select Submodules... (enabled only when the repository contains submodules), or select Open on a modified submodule in the Unstaged files area.
Note:
The tooltip (via hover) for a modified submodule shows both the currently tracked commit and the previously tracked commit.
Edit online

Work with Worktrees

Open an existing Git worktree as a working copy in the Git Staging view.

A worktree is an additional working copy of a repository checked out to its own folder. The Git Client treats worktrees like any other working copy.

Open the worktree's folder as a working copy, the same way you open any repository.
Note:
The Git Client cannot create worktrees. Create them from a terminal with the git worktree command, then open them from the Git Staging view.
Edit online

Work with Large Files (Git LFS)

The Git Client detects and handles files tracked with Git Large File Storage.

Install Git LFS by following the instructions at git-lfs.com.

Once Git LFS is installed and files are tracked, the Git Client detects and handles them automatically.

Note:
If you connect through a proxy, LFS operations need the HTTPS_PROXY environment variable set. See Git LFS Fails Behind a Proxy.
Edit online

Configure the Git Client

Adjust how the Git Client behaves through its preferences pages, validation options, and editor variables.

The Git Client contributes several preferences pages to Oxygen, under Options > Preferences > Plugins > Git Client:

You can also validate files before you commit or push, and use Git editor variables in scenarios and templates.

Edit online

Git Client Preferences

The options on the main Git Client preferences page.

Overview

To open the Git Client preferences pages, go to Options > Preferences > Plugins > Git Client, or select Preferences from the Vertical Ellipsis menu.

Figure 9. Git Client Preferences Page
OptionDefaultDescription
When detecting a Git repository inside a newly opened projectAlways askControls what happens to the current working copy when you open a project that contains a Git repository. The available options are Always switch to the new working copy, Never switch to the new working copy, and Always ask.
Check for local branches whose remote branch no longer existsSelectedChecks for local branches whose remote branch was deleted and offers to remove them. Clear this option to stop the check and its Outdated branches detected notification. You can also turn it off from the notification by selecting the Don't show this again checkbox.
Notify me about new commits in the remote repositoryClearedShows a notification when new commits are available in the remote repository.
Update all submodules after pulling changes from the remote repositorySelectedUpdates all submodules whenever you pull changes.
Detect and open Oxygen projects (.xpr) from opened working copiesClearedOpens an Oxygen project found in a working copy. If one .xpr file is found, it opens automatically. If several are found, you can choose which one to open.
Validate each file before committingSelectedValidates each file before it is committed and stops the commit if problems are found. Select Allow commit despite validation problems to add a Commit anyway button to the dialog box. For details, see Validate Before Commit and Push.
Validate all files from the project's "Main Files" folder before pushingSelectedValidates the files in the Main Files folder before a push. Select Allow push despite validation problems to add a Push anyway button to the dialog box. For details, see Validate Before Commit and Push.
Global Options/Project OptionsGlobal OptionsChoose Project Options to store these settings in the project file (.xpr) so that you can share them with your team.
Edit online

SSH Connections Preferences

The options on the Git Client SSH Connections preferences page.

Overview

Open the Git Client preferences page, then select the SSH Connections page.

Figure 10. SSH Connections Preferences Page (Windows)
Figure 11. SSH Connections Preferences Page (Linux and macOS)
OptionDefaultDescription
Use SSH AgentSelectedAuthenticates through an SSH agent so keys stored in it are used automatically. On Windows, choose Win32-OpenSSH (default) or Pageant. On Linux and macOS the Git Client uses the standard Unix domain socket.
SSH Passphrase-Shows whether an SSH passphrase is currently stored. Select Clear to remove it, independently of your host credentials.
Edit online

AI Preferences

The options on the Git Client AI preferences page, where you tune how AI features behave.

Overview

Important:
This feature requires the Oxygen AI Positron add-on.

Open the Git Client preferences page, then select the AI page.

Each AI feature has an Additional Instructions box where you add your own guidance. Save these settings to the project file to share them with your team.

Figure 12. AI Preferences Page
OptionDefaultDescription
Commit Message Generation-Extra instructions for the commit-message generator. They take priority over the built-in guidelines. Generation can also draw on the current branch name, recent commit messages, and any draft text you have typed.
Explain Commits-Extra instructions for commit explanations.
Conflict Resolution-Extra instructions for AI conflict resolution.
Maximum characters sent to AI2,095,152The maximum number of characters sent to the AI as context.
Recent commits to include for context5How many recent commit messages to include as style context (0–50). The AI uses them to match your project's commit-message conventions.
Edit online

Credentials Preferences

The stored credentials are shown in the Git Client Credentials preferences page.

Overview

Open the Git Client preferences page, then select the Credentials page. It lists the HTTP and token credentials that the Git Client has stored for Git servers.

Figure 13. Credentials Preferences Page
Column or actionDefaultDescription
Host-The Git server host for which credentials are stored.
Type-The stored authentication type, such as Personal access token or Basic authentication.
Username-The username associated with basic authentication credentials, when available.
RemoveDisabled until an entry is selectedRemoves the selected stored credentials after you apply the preferences changes. To remove credentials for multiple servers, select multiple rows before selecting Remove.
Edit online

Git Editor Variables

The Git Client contributes editor variables you can use wherever Oxygen accepts them.

Variable Expands to
${git(working_copy_name)} The name of the working copy directory.
${git(working_copy_path)} The absolute file path of the working copy directory.
${git(working_copy_url)} The location of the working copy directory as a URL.
${git(short_branch_name)} The short name of the current branch (for example, dev).
${git(full_branch_name)} The full name of the current branch (for example, refs/heads/dev).
Edit online

Reference

Look up every control in the Git Client's views and menus, and every action it provides.

This section is for reference lookup. The interface reference describes each view and menu control by control. The Git Actions Reference lists every Git action, what it does, and where to find it.

Edit online

Git Staging View

The controls in the Git Client Git Staging view, region by region.

Overview

Open the Git Staging view from Window > Show View > Git Staging, from Tools > Git Client, or from the Git menu.

Figure 14. Git Staging View

Toolbar

Control Description
Push Sends your local commits to the remote.
Pull Brings remote commits into your branch. In the Vertical Ellipsis menu, the pull actions are grouped under a Pull submenu (same as in the Git menu).
Stash Stashes changes or lists existing stashes.
Show current repository history Opens the Git History view for the current repository.
Show Git Branch Manager view Opens the Git Branch Manager view.
Vertical Ellipsis Opens a menu with repository setup, synchronization, ignore, configuration, and credential actions.

Header

Control Description
Working copy Selects the active working copy, or browses for one on disk.
Branch Shows the current branch and switches to another local branch.

File Areas and Stage Controls

The Unstaged files area lists changed files, while the Staged files area lists files ready to commit. The actions between them move files back and forth (Stage selected, Stage all, Unstage selected, and Unstage all). Right-click a file for contextual actions such as compare, open, stage, discard, resolve conflict, show history, show blame, and show in the system file manager. Use Switch to tree/list view to toggle the view mode between a flat list and a folder tree.

Commit Area

Enter a message in the Commit message area and select Commit. The message toolbar includes the following actions: Generate commit message using AI, Choose a previously used comment, Amend last commit, and Automatically push changes to remote branch.

Edit online

Git History View

The controls in the Git Client Git History view.

Overview

Open the Git History view from the Show current repository history toolbar button, from Window > Show View, or from a Show history action in a contextual Git submenu.

Figure 15. Git History View

Toolbar and Filter

  • The branch chooser filters the graph: all branches, all local branches, the current branch, or the current local branch.
  • Link with editor (enabled by default) keeps the history synchronized with the active editor.
  • You can use the text filter to narrow the list by message, date, author, commit ID, branch, or tag. When the field contains text, a clear (X) button appears. Clearing the filter keeps your current selection visible.

Status Labels

A status bar shows the current working copy, the branch, and the file whose history is displayed (when you are viewing the history of a single resource). These labels are interactive:

  • Select the branch link to scroll the history table to the tip of that branch.
  • Select the X next to the file to clear the file filter and show the full repository history again. Disabling Link with editor also clears the file filter.

History Table

Each row shows the graph, message, date, author, and commit ID, with the latest commit first. When the working copy has uncommitted changes, a gray Uncommitted changes node appears at the top of the graph to represent the future commit (it disappears after you commit or discard those changes).

Right-click a commit to access actions such as Create Tag, Cherry-Pick, Revert Commit, Reset Branch to Commit, Rebase..., and Explain commit with AI. For the tip commit of the current branch, the contextual menu also includes Pull (the pull action follows the type set in your preferences) and Push. These actions appear only when the branch has a tracked remote, and after a pull the view scrolls to the new tip.

Branch labels on a commit are interactive. Double-click a label to switch to that branch. Hover over a label to see its details. For a local branch, the tooltip shows the name, a current-branch marker, its tracking branch, and how far ahead or behind it is (counts of 100 or more are shown as 99+). For a remote branch, it shows the local branches that track it. The current local branch label is highlighted. Right-click a label (rather than elsewhere on the row) to access label-specific actions:

  • Go to tracking branch (local branch) or Go to local branch (remote branch) - Selects the tip commit of the related branch.
  • Delete... - Removes a local branch, after a confirmation.
  • Show in Branch Manager - Opens the Branch Manager with the branch selected (local or remote).
Figure 16. Branch Label Tooltip

Commit Details and Affected Resources

The Commit Details pane shows the commit ID, parent, author, date, committer, any refs (branches and tags) on the commit, and the message. The committer date is shown next to the committer only when it differs from the author date (for example, after a rebase, cherry-pick, or amend). The Affected Resources pane lists the files changed by the commit. Right-click a file to access these actions (the available actions depend on how the file changed). You can select several files and apply actions to all of them at once, except for the compare actions, which work on one file at a time. In a comparison, the panes are labeled Newer and Older, each followed by the revision it shows:

Open Previous Version
Opens the file as it was before this commit.
Open Working Copy Version
Opens the current version from your working copy.
Reset File to This Commit
Restores the file to its state in this commit.
Compare with Previous Version
Compares this commit's version with the previous one.
Compare with Working Copy Version
Compares this commit's version with your working copy.
Compare with Each Other
When you select a range of commits, compares the file between the two endpoint versions.

When you select a range of commits, the bottom-left pane identifies the two revisions being compared (the newest and oldest in your selection), and the bottom-right pane lists the files changed between them.

When you select the Uncommitted changes row, these two panes show your pending changes instead: the bottom-left pane lists the Staged files, and the bottom-right pane lists the Unstaged files. Both are kept synchronized with the Git Staging view.

Right-click a file to open, compare, stage, unstage, or discard it (see Review, Compare, Stash, Stage, and Commit Actions). You can select and right-click on multiple files to stage, unstage, or discard all of them all at once. A staged row opens and compares the same version (similar to the Git Staging view), and it offers Open working copy version for a file that you edited again after you staged it.

Edit online

Git Branch Manager View

The controls in the Git Client Git Branch Manager view.

Overview

Open the Git Branch Manager view from the Show Git Branch Manager view toolbar button, from Window > Show View, or with Show branches in the Git menu.

Figure 17. Git Branch Manager View

Branch Tree

The tree groups branches under Local and Remote nodes. Every configured remote appears under Remote, including remotes that you have not fetched from yet. Hovering a branch shows its last commit's author and date, and hovering a remote shows its URL. Opening the view or using Refresh fetches in the background. Right-click the Remote node to fetch all remotes or a single remote such as origin.

Two markers indicate when the fetch configuration limits what the tree can show:

(partial)
On a remote, this means its fetch configuration downloads only some of its branches. The tooltip lists the configuration. Select Fetch all branches... to download all of them from now on.
(not fetched)
On a local branch, this means the branch tracks a remote branch that is not downloaded, so the Git Client cannot determine locally whether that remote branch is still available or how far ahead or behind you are. Select Fetch branches used locally... to add the upstream branches tracked by your local branches to the fetch configuration.

Remote Actions

Right-click the Remote node to Add remote repository..., or right-click a remote to Edit remote repository... or Delete remote. Renaming a remote preserves its settings, its remote-tracking branches, and the tracking of every local branch that follows it. You can also manage the same remotes in the Manage remote repositories... dialog box.

Branch Actions

Right-click a local branch for Checkout, Create Branch, Merge, Squash Merge, Track Remote Branch, Push, Pull, Show in History, and Delete Branch. For a remote branch, use Checkout to create a matching local branch.

Edit online

Git Menu and Contextual Actions

The top-level Git Client menu and the contextual Git actions in other views and editors.

Git Menu

The Git menu groups repository-level commands:

  • Repository setup - Clone repository..., Open repository..., Create repository in project, Show working copy in.
  • Synchronization - Push, Pull (with merge, rebase, and other-branch options), and Fetch.
  • Views and information - Show staging, Show branches, Show tags..., Show history, Submodules....
  • Stash - Stash changes..., List stashes....
  • Ignore files - Ignore submenu, which provides access to the repository .gitignore and global ignore files.
  • Remote and preferences - Manage remote repositories..., Track remote branch..., Edit repository "config" file, and Preferences.

Contextual Actions

A contextual Git submenu appears in the Project view, DITA Maps Manager, and the editor, offering the Git actions that apply to the selected resource, such as staging, comparing, showing history, and showing blame. For a folder in the Project view that is not yet a repository, the only action is Create repository here.

Edit online

Git Actions Reference

Every Git Client action, grouped by area, with what it does and where to find it.

Each action is defined once here. The tables are grouped by area:

Edit online

Repository and Working Copy Actions

Actions for creating, cloning, and opening repositories.

Action Description Available from
Clone repository... Creates a local copy of a remote repository and sets it as the working copy. Git menu, Vertical Ellipsis menu
Open repository... Opens a repository already on disk as the working copy. Git menu, Working copy drop-down
Create repository in project Turns the current project folder into a Git repository. Git menu, Vertical Ellipsis menu
Create repository here Turns a selected folder into a Git repository. Project view contextual menu
Show working copy in Opens the working copy folder in the system file manager or a terminal. Git menu
Edit online

Review, Compare, Stash, Stage, and Commit Actions

Actions for reviewing, stashing, staging, and committing local changes.

Action Description Available from
Open Opens the selected file, folder, or submodule. For a staged file that you edited again after you staged it, this opens the staged version in read-only mode because that is the version that the row contributes to the next commit. File area contextual menu
Open working copy version Opens the editable file from the working copy. This option is available for a staged file that you edited again after staging it. In that case, the Open action opens the staged version instead. File area contextual menu, Git History view uncommitted changes
Open in compare editor Opens the file in the compare editor to show the changes. File area contextual menu, double-click
Copy relative path Copies the path of each selected file or folder, relative to the repository root, ready to paste into a .gitignore file, a command line, or a review comment. A folder contributes its own path, and a multiple selection is copied one path per line. File area contextual menu, Git History view affected files
Copy previous path Copies the name a renamed file had before the rename. Shown only for a renamed file, whose earlier name appears nowhere else. Git History view affected files
Git Diff Compares the selected resource with its repository version, without going through the staging workflow. Project view Git submenu
Stash changes... Shelves all uncommitted changes and cleans the working copy. Stash drop-down, Git menu
Stash selected files... Shelves only the selected files (both their staged and unstaged changes), reverting them to the last committed state. Unavailable when the selection contains conflicts. File area contextual menu
List stashes... Opens the stashes dialog box to apply or remove stashes. Stash drop-down, Git menu
Apply Restores the selected stash to the working copy. Stashes dialog box
Delete / Delete all Removes the selected stash, or clears every stash. Stashes dialog box
Stage selected Moves the selected files to the staged area. Git Staging view; Git History view uncommitted changes row
Stage all Moves all changed files to the staged area. Git Staging view
Unstage selected Moves the selected files back to the unstaged area. Git Staging view; Git History view uncommitted changes row
Unstage all Moves all staged files back to the unstaged area. Git Staging view
Discard Reverts the selected files to their last committed state. File area contextual menu; Git History view uncommitted changes row
Commit Records the staged changes as a commit in the local repository. Git Staging view
Generate commit message using AI Drafts a commit message from the staged changes, using AI Positron. Commit message toolbar
Choose a previously used comment Reuses a message from a recent commit. Commit message toolbar
Amend last commit Adds the staged changes to the most recent local commit, or edits its message. Commit message toolbar
Automatically push changes to remote branch Pushes the commit to the remote immediately after committing. Commit message toolbar
Edit online

Synchronization and Conflict Actions

Actions for pushing, pulling, fetching, and resolving conflicts.

Action Description Available from
Push Sends local commits to the remote branch the current branch tracks. A Push to submenu pushes to a specific remote instead. Git Staging toolbar, Git menu, branch contextual menu, History current-branch tip commit
Pull (merge) Pulls remote changes and integrates them with a merge commit. Pull drop-down, Git menu, branch contextual menu, History current-branch tip commit
Pull (rebase) Pulls remote changes and replays local commits on top for a linear history. Pull drop-down, Git menu, branch contextual menu, History current-branch tip commit
Pull... Pulls from a branch other than the tracked one. Pull drop-down, Git menu
Fetch Downloads remote commits and refs without merging. Git menu, Vertical Ellipsis menu, Branch Manager
Fetch all branches... Changes a remote's fetch configuration to download all of its branches, then fetches. Offered on a remote marked (partial). Git Branch Manager contextual menu (remote node)
Fetch branches used locally... Adds the upstreams your local branches track to a remote's fetch configuration, then fetches. Offered when a local branch is marked (not fetched). Git Branch Manager contextual menu (local branch or remote node)
Resolve Using "Mine" Resolves a conflict by keeping your version. Conflict submenu
Resolve Using "Theirs" Resolves a conflict by keeping the incoming version. Conflict submenu
Mark Resolved Marks a manually edited file as resolved and stages it. Conflict submenu
Resolve with AI AI Positron proposes a resolution for a conflicting file. Conflict submenu
Abort Cancels an in-progress operation and restores the prior state. Conflict panel
Restart Re-starts an in-progress operation. Conflict panel
Continue Completes an in-progress operation once conflicts are resolved. Conflict panel
Edit online

Branch, Tag, History, and Blame Actions

Actions for working with branches, tags, history, and blame.

Action Description Available from
Checkout Checks out an existing branch, a new branch, or a commit in detached HEAD. History view, Branch Manager
Create Branch Creates a branch from a commit or branch. History view, Branch Manager
Track Remote Branch Sets a local branch to track a remote branch, or removes its tracking with Do not track any remote branch. A branch whose remote branch no longer exists on the server is listed with a (not available) suffix and keeps its tracking, so a push recreates that branch. Branch Manager, Git menu
Merge Merges the selected branch or commit into the current one. Branch Manager, Git History contextual menu
Squash Merge Merges the selected branch as a single squashed commit. Branch Manager
Rebase... Replays local commits onto the selected commit. This requires a force push afterward. History view contextual menu
Cherry-Pick Copies a single commit to the current branch. History view contextual menu
Revert Commit Adds a commit that undoes the selected commit. This is safe for shared commits. History view contextual menu
Reset Branch to Commit Moves the current branch to the selected commit. Use this action with care. History view contextual menu
Delete Branch Deletes the selected local branch. Branch Manager, branch label contextual menu
Show in History Shows the selected branch in the History view. Branch Manager
Show in Branch Manager Shows the selected branch in the Branch Manager. History view branch label contextual menu
Go to tracking branch Selects the tip commit of the tracking branch for the local branch. History view local branch label contextual menu
Go to local branch Selects the tip commit of a local branch that tracks the selected remote branch. History view remote branch label contextual menu
Create Tag Creates a tag on the selected commit. History view contextual menu
Show tags... Opens the Tags dialog box, where you can check out, push, or delete tags. Git menu, Vertical Ellipsis menu
Explain commit with AI Summarizes one or more commits with AI Positron. History view contextual menu
Show Blame Colors each line in a file based on the commit that last changed it. File area, editor, Project view, DITA Maps Manager
Hide Blame Turns off blame coloring. Editor, contextual menus
Edit online

Advanced Repository Actions

Actions for submodules.

Action Description Available from
Submodules... Opens a submodule as the working copy. Git menu, Vertical Ellipsis menu
Edit online

Configuration and Preferences Actions

Actions for managing remotes, configuration, preferences, and credentials.

Action Description Available from
Manage remote repositories... Adds, renames, edits, or deletes the remotes for the repository. Git menu, Vertical Ellipsis menu
Add remote repository... Adds a remote to the repository. Git Branch Manager contextual menu (Remote node)
Edit remote repository... Changes a remote's name or URL. Renaming preserves the remote's settings, its remote-tracking branches, and the tracking of every local branch that followed it. Git Branch Manager contextual menu (remote node)
Delete remote Removes a remote and its remote-tracking branches. Git Branch Manager contextual menu (remote node)
Edit repository "config" file Opens the repository's config file for editing. Incorrect values can affect push, pull, and branch tracking behavior. Git menu, Vertical Ellipsis menu
Preferences Opens the Git Client preferences pages. Git menu, Vertical Ellipsis menu, Options
Edit online

Troubleshooting

Solutions to the problems you are most likely to run into with the Git Client.

Each topic in this section describes a symptom, explains why it happens, and tells you how to fix it.

Edit online

Push Is Rejected Because the Branch Is Behind

If the remote has commits you do not have yet, the Git Client blocks the push until you catch up.

Problem

A push fails and the Git Client reports that your current branch is behind its remote counterpart.

Figure 18. Push Rejected Error

Cause

Someone pushed commits to the remote branch after your last pull, so your local branch no longer includes the latest remote history. Git refuses the push to avoid overwriting those commits.

Solution

  1. Pull the remote changes into your local branch.
  2. Resolve any conflicts that the pull reports.
  3. Push again.
Edit online

Authentication Fails (GitHub, GitLab, Bitbucket)

Most sign-in failures come down to using a password where the server now requires a token.

Problem

A push, pull, fetch, or clone over HTTPS is rejected with an authentication error, even though your username and password look correct.

Cause

The server may no longer accept account passwords for Git operations, or your account uses two-factor authentication.

Solution

  1. Create a personal access token in your Git server account.
    • GitHub no longer accepts account passwords. Use a personal access token.
    • Bitbucket app passwords can no longer be created (as of September 9, 2025); create an API token with the required scopes and use it as the password with your Bitbucket username.
    • If your account uses two-factor authentication, you must use a token rather than your password.
  2. Enter the token when the Git Client prompts you. See Authenticate over HTTPS.
Edit online

Cannot Install from the Update Site

If Oxygen cannot reach the update site, install from a downloaded package instead.

Problem

The add-on does not install, and the update-site URL cannot be reached.

Cause

A network restriction or proxy is blocking the connection to the update site.

Solution

  1. Download the add-on package and unzip it.
  2. In Help > Install new add-ons, select Browse for local files and choose the addon.xml file from the unzipped package.

    See Install Manually from a File or Update Site for the full procedure.

Edit online

Git LFS Fails Behind a Proxy

Git LFS operations need the proxy configured through an environment variable.

Problem

Git LFS transfers fail when you connect through a proxy, even though ordinary Git operations work.

Cause

Git LFS does not pick up the proxy from the Git configuration. It reads it from the environment.

Solution

Set the HTTPS_PROXY environment variable to your proxy before starting Oxygen.

For example, on Windows:

set HTTPS_PROXY=http://my.proxy.com:5000
Edit online

Rebase or Merge Is Blocked

The Git Client will not start a rebase or merge while conflicts or uncommitted changes are outstanding, or when the Git configuration forbids the merge.

Problem

A rebase or merge does not start, or it stops immediately.

Cause

There are unresolved conflicts from an earlier operation, or uncommitted changes that the operation would overwrite.

Solution

  1. Resolve any outstanding conflicts and finish the in-progress operation.
  2. Commit or stash your uncommitted changes.
  3. Start the rebase or merge again.

Cause

The Git configuration forbids the merge, and the Git Client reports that the merge was not performed. Under merge.ff = only, a merge of branches that have diverged is refused. A Squash Merge is refused under merge.ff = false.

Note:
This setting is often in ~/.gitconfig, where it applies to every repository on the machine rather than only to the current one.

Solution

  1. Change the merge.ff setting, or remove it to restore the Git default.
  2. Alternatively, run a merge that the configuration permits.

    Under merge.ff = only, pull or rebase first so that the branches no longer diverge.

Edit online

Repository Shows as Outdated

The Git Client periodically checks for local branches whose remote branch was deleted, and offers to clean them up.

Problem

An Outdated branches detected notification appears when you open a working copy, and then again about every 3.5 hours.

Cause

The Git Client checks for local branches whose remote branch no longer exists and offers to delete them. This is helpful, but it can be intrusive if you switch working copies often.

Solution

  1. Delete the branches you no longer need from the notification.

    If the branch is currently checked out, you must switch to a different branch before you can delete it.

  2. To stop the check, clear Check for local branches whose remote branch no longer exists in the preferences, or select Don't show this again in the notification.
Edit online

The Git Client Reports a Filesystem Name Collision

Tracked files whose names differ only in case or accent collide on your file system, so the Git Client flags them and blocks risky operations.

Problem

A Filesystem name collision warning appears in the Git Staging view, and one or more files in the Unstaged files area are marked with a Path Collision icon. You cannot stage or discard those files, and stashing (along with the pull and pre-push operations that stash internally) is refused.

Cause

Two files tracked in the repository have names that differ only in letter case or Unicode form (for example, an accented and an unaccented spelling of the same name). On a case-insensitive or Unicode-folding file system (such as macOS APFS or Windows), both names resolve to a single physical file, so the two entries cannot be represented safely. Round-tripping them through a stash would delete the file, so the Git Client refuses those operations until you resolve the collision.

Solution

  1. Decide which of the two colliding names to keep.

    Because both names map to the same file on this file system, the Git Client cannot stage or discard them for you. Resolve the collision with command-line Git.

  2. From a command line in the repository, remove the other name from Git without deleting the file on disk.

    git rm --cached "the-other-name.txt"

    Note:
    Alternatively, open the repository on a case-sensitive file system, where the two files are distinct, and rename or delete one of them there.
  3. Commit the change.

    Only one entry remains, so the warning clears and the held operations become available again.