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.
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.
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:
- Drag an Install button into the editor. This is the quickest way and works in Oxygen 26.1 and newer.
- Install from the update site or a downloaded package. Use this when the drag-and-drop button is not available or the update site cannot be reached.
After you restart, the three Git views (Staging, History, Branch Manager), the Git menu, and the contextual Git actions become available.
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.
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.
Tour the Git Client Interface
The Git Client spreads its work across three views, a menu, and contextual actions.
| Location | Use it to |
|---|---|
| Review changes, stage them, commit, and push or pull. This is your day-to-day workspace. | |
| Explore the commit graph, inspect a commit, compare revisions, and see which files a commit changed. | |
| 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
, or
open the
Git Staging
view and use its toolbar to reach the other two.
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.
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.
The Git Client stores the credentials for that server and stops prompting. To review or remove them later, see Manage Credentials.
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.
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.
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.
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.
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:
- Clone a Repository - Download a copy of an existing remote repository.
- Create a Repository from Your Project - Put an existing local project under version control.
- Open an Existing Working Copy - Point the Git Client at a repository already on your machine.
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.
The Git Client clones the repository and sets it as the current working copy.
Create a Repository from Your Project
Put an existing project under version control by turning its folder into a Git repository.
- 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.
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.
Open an Existing Working Copy
Point the Git Client at a Git repository that is already on your machine.
-
In the
Git Staging
view, open the
Working copy
drop-down.
-
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.
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.
The Git Client records the staged changes as a commit in your local repository. Push the changes when you are ready to share them.
Compare Changes Before Committing
See exactly what changed in a file (including images) before you stage or commit.
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.
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.
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.
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.
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.
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.
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.
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.
- 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.
To edit the rules directly, open the
Vertical Ellipsis
menu and choose
Open project .gitignore
or
Open global ignore file.
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.
Push Commits
Send your local commits to the remote repository so others can see them.
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.
git remote set-url --add --push <remote>
<url>. The Git Client pushes by remote name, so one 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.
- 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.
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.
- 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 originto 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.
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.
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.
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.
- Right-click the conflicting file and open the Resolve conflict submenu.
-
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.
- 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
The Git Client stages each resolved file automatically. When all files are resolved, finish the operation (see Track and Finish an In-Progress Operation).
Resolve Conflicts with AI
Let AI Positron analyze a conflict and propose a resolution you can review and apply.
The Git Client writes the resolution to your working copy and stages the file.
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.
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.
Switch to Another Branch
Change the current local branch from the Git Staging view or the Branch Manager.
- 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.
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.
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.
Create a Branch
Branch from the current HEAD or from any commit in the
history.
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.
- 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.
Revert or Reset Commits
Undo commits, either by adding an inverse commit (revert) or by moving the branch pointer back (reset).
- 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.
Create and Manage Tags
Tag a commit to mark a release or milestone, then push, check out, or delete the tags.
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.
Inspect and Compare Commits
Review a single commit, compare a range of revisions, or compare your working copy against an earlier one.
Explain a Commit with AI
Get a plain-language summary of the changes for one or more commits.
The AI Positron view opens with a summary of the selected commits. Customize how it writes summaries on the AI preferences page.
Show Blame
See who last changed each line of a file, and jump to the commit behind any line.
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:
- Work with Submodules - Repositories nested inside your repository.
- Work with Worktrees - Multiple working copies of one repository.
- Work with Large Files (Git LFS) - Binary and large files tracked with Git LFS.
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.
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.
git
worktree command, then open them from the Git Staging view.Work with Large Files (Git LFS)
The Git Client detects and handles files tracked with Git Large File Storage.
Once Git LFS is installed and files are tracked, the Git Client detects and handles them automatically.
HTTPS_PROXY
environment variable set. See Git LFS Fails Behind a Proxy.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 :
- Git Client Preferences - General behavior and validation.
- SSH Connections Preferences - SSH agent and passphrase.
- AI Preferences - AI instructions and context limits.
- Credentials Preferences - Stored HTTP and token credentials.
You can also validate files before you commit or push, and use Git editor variables in scenarios and templates.
Git Client Preferences
The options on the main Git Client preferences page.
Overview
To open the Git Client preferences pages, go to , or select
Preferences from the
Vertical
Ellipsis menu.
| Option | Default | Description |
|---|---|---|
| When detecting a Git repository inside a newly opened project | Always ask | Controls 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 exists | Selected | Checks 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 repository | Cleared | Shows a notification when new commits are available in the remote repository. |
| Update all submodules after pulling changes from the remote repository | Selected | Updates all submodules whenever you pull changes. |
| Detect and open Oxygen projects (.xpr) from opened working copies | Cleared | Opens 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 committing | Selected | Validates 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 pushing | Selected | Validates 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 Options | Global Options | Choose Project Options to store these settings in the project file (.xpr) so that you can share them with your team. |
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.
| Option | Default | Description |
|---|---|---|
| Use SSH Agent | Selected | Authenticates 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. |
AI Preferences
The options on the Git Client AI preferences page, where you tune how AI features behave.
Overview
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.
| Option | Default | Description |
|---|---|---|
| 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 AI | 2,095,152 | The maximum number of characters sent to the AI as context. |
| Recent commits to include for context | 5 | How many recent commit messages to include as style context (0–50). The AI uses them to match your project's commit-message conventions. |
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.
| Column or action | Default | Description |
|---|---|---|
| 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. |
| Remove | Disabled until an entry is selected | Removes the selected stored credentials after you apply the preferences changes. To remove credentials for multiple servers, select multiple rows before selecting Remove. |
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). |
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.
Git Staging View
The controls in the Git Client Git Staging view, region by region.
Overview
Open the
Git Staging
view from , from
, or
from the Git
menu.
Toolbar
| Control | Description |
|---|---|
| Sends your local commits to the remote. | |
| 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). | |
| Stashes changes or lists existing stashes. | |
| Opens the Git History view for the current repository. | |
| Opens the Git Branch Manager view. | |
| 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.
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 , or from a Show history action in a contextual Git
submenu.
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).
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.
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
, or
with
Show branches
in the Git
menu.
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.
Git Menu and Contextual Actions
The top-level Git Client menu and the contextual Git actions in other views and editors.
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:
Repository and Working Copy Actions
Actions for creating, cloning, and opening repositories.
| Action | Description | Available from |
|---|---|---|
| Creates a local copy of a remote repository and sets it as the working copy. | Git menu, Vertical Ellipsis menu | |
| 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 |
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 |
| 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 |
| Moves the selected files to the staged area. | Git Staging view; Git History view uncommitted changes row | |
| Moves all changed files to the staged area. | Git Staging view | |
| Moves the selected files back to the unstaged area. | Git Staging view; Git History view uncommitted changes row | |
| 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 |
| Drafts a commit message from the staged changes, using AI Positron. | Commit message toolbar | |
| Reuses a message from a recent commit. | Commit message toolbar | |
| Adds the staged changes to the most recent local commit, or edits its message. | Commit message toolbar | |
| Pushes the commit to the remote immediately after committing. | Commit message toolbar |
Synchronization and Conflict Actions
Actions for pushing, pulling, fetching, and resolving conflicts.
| Action | Description | Available from |
|---|---|---|
| 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 |
| 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 |
| 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 |
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 |
| Opens the Tags dialog box, where you can check out, push, or delete tags. | Git menu, Vertical Ellipsis menu | |
| 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 |
Advanced Repository Actions
Actions for submodules.
| Action | Description | Available from |
|---|---|---|
| Opens a submodule as the working copy. | Git menu, Vertical Ellipsis menu |
Configuration and Preferences Actions
Actions for managing remotes, configuration, preferences, and credentials.
| Action | Description | Available from |
|---|---|---|
| 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 |
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.
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.
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
- Pull the remote changes into your local branch.
- Resolve any conflicts that the pull reports.
- Push again.
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
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
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
HTTPS_PROXY environment variable to your proxy before
starting Oxygen.
For example, on Windows:
set HTTPS_PROXY=http://my.proxy.com:5000
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
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.
Solution
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
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
Resources
Webinars, presentations, and articles about the Git Client and using Git for documentation.
Webinars, Presentations, and Articles
- Webinar: Add-ons You Can Use for Technical Writing
- Webinar: Extending the Functionality of Oxygen Using Add-ons
- Webinar: Docs as Code: Documentation Management Inspired by Software Development
- Webinar: Using DITA for Small Technical Documentation Teams
- Blog Post: Using Git for Technical Writing
- Video: Validating Files Before Commit and Push