Edit online

Git Client Add-on

An add-on is available that contributes a built-in Git client directly in Oxygen JSON Editor. Once the add-on is installed, a Git Staging view is available that includes various actions that perform common Git commands, such as push, pull, change branch, commit, and more. It also includes a built-in tool for comparing and merging changes.

Quick Installation

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

Install

Manual Installation

To manually install the add-on, follow this procedure:
  1. Go to Help > Install new add-ons to open an add-on selection dialog box. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
    Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
  2. Select the Git Client add-on and click Next.
  3. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
  4. Restart the application.

Result: The Git Staging view is now available. To open the view, select Git Staging from the Window > Show View menu (or select Git Client from the Tools menu). This view acts as a Git client integrated directly in Oxygen JSON Editor, and it provides support for committing changes to a Git repository, comparing and merging changes, resolving conflicts, and other Git commands. A Git menu is also contributed in the main menu bar that includes various Git actions.

Git Staging View Interface

Once the Git Client add-on is installed, the Git Staging view is available by selecting it from the Window > Show View menu (or select Git Client from the Tools menu). The Git Staging view is the main interface where most of the actions that trigger Git commands and other features can be accessed.

Figure 1. Git Staging View

The Git Staging view includes the following actions/features (most are also available in the Git menu):

Push
Pushes your local repository changes to the remote repository. The arrow icon has a small plus sign in the bottom-right corner when there are changes that have not yet been pushed to the repository.
Pull
Pulls the changes from the remote repository into your local repository.
Stash drop-down menu
Includes the following submenu items:
Stash changes
Creates a new stash from the working copy changed file.
List stashes
Opens a dialog box that lists the existing stashes and you can choose to apply or remove a stash.
Show current repository history
Opens the Git History view at the bottom of the application.
Show Git Branch Manager view
Opens the Git Branch Manager view on the right side of the application.
Ellipsis (three vertical dots) menu
Includes the following submenu items:
Clone new repository
Clones a repository into a new directory.
Push
Pushes your local repository changes to the remote repository.
Pull (merge)
Pulls the latest changes from the remote repository and combines them with your local unpublished changes by creating one new merge commit.
Pull (rebase)
Pulls the latest changes from the remote repository, rewrites their commits, and reapplies them on top of your local unpublished changes.
Show branches
Opens the Git Branch Manager view on the right side of the application.
Show tags
Opens a dialog box that lists all the tags. You can delete tags, checkout a certain tag, or push a tag that is only present in the local branch to the remote.
Show history
Opens the Git History view at the bottom of the application.
Submodule
Opens a combo box where you can select the desired submodule to open and work with.
Stash changes
Creates a new stash from the working copy changed file.
List changes
Opens a dialog box that lists the existing stashes and you can choose to apply or remove a stash.
Manage remote repositories
Opens a dialog box where you can add, edit, or delete existing remote repositories.
Track remote branch
Opens a dialog box where you can select a remote branch that the local branch will track for executing fetch, push, or pull commands.
Edit repository "config" file
Opens the configuration file for the repository in the main editor so that it can be edited.
Preferences
Opens the Git Client preferences page where you can configure some options that relate to the add-on.
Reset all credentials
Resets all credentials to the default values.
Unstaged files area
Any changed, unstaged files are listed in this box. The following actions are available at the top-right corner of the box:
Stage selected
Moves the selected unstaged, changed files to the Staged files area.
Stage all
Moves all unstaged, changed files to the Staged files area.
Switch to tree view
Switches to a tree-like view.
Staged files area
All staged files are listed in this box. The following actions are available at the top-right corner of the box:
Unstage selected
Moves the selected staged files to the Unstaged files area.
Unstage all
Moves all staged files to the Unstaged files area.
Switch to tree view
Switches to a tree-like view.
Commit message area
This box in this area is used to write a commit message. The following actions are available at the top-right corner of the box:
Choose a previously used comment
Allows you to re-use a commit message that you used in the past.
Automatically push changes to remote branch
When a commit is performed, the committed changes are also pushed to the remote repository.
Ammend last commit
Allows you to edit the selected commit. You can combine staged changes with the previous commit instead of creating an entirely new commit. It can also be used to simply edit the previous commit message without changing its snapshot. This action should not be performed on public commits (commits that were pushed to the remote repository).

Cloning a Repository

Click the Clone new repository button (it has a '+' sign as the icon) and provide the following:
  • Repository URL - The URL of the remote repository to be cloned.
  • Checkout branch - A specific branch of the repository that is being cloned. The default branch will be cloned if another one is not specified.
  • Destination path - The local path where the repository will be cloned. When you enter a URL of a repository, it will be proposed to automatically save it in a folder with the same name.

After cloning a repository, it will automatically be set as the current working copy.

Making an Oxygen Project a Git Repository

When showing the Git Staging side-view after opening an Oxygen JSON Editor project that is not already a Git repository, Oxygen JSON Editor offers the possibility to make that project also a local Git repository. This is very useful, for example, for newly created projects. After creating the local repository, bind it to a remote repository. You will be asked to specify the URL of the corresponding remote repository on your first attempt to push or pull changes.

Authentication

The Git Client supports HTTPS and SSH connections to GitHub, GitLab, Bitbucket, and more. It also includes support for ssh-agent forwarding.

Note: For SSH connections, you can use the SSH agent to use the SSH keys already stored on it. To enable support for SSH agent access, go to Git(Menu) > Settings > Preferences > SSH Connections (or Git Staging View > Ellipsis menu > Preferences > SSH Connections) and select the Use SSH Agent option.

To access the remote repository, you need to provide your authentication details (if not using unprotected SSH keys). If no such information is found in the add-on's settings, you will be prompted for them.

The Git Client allows you to authenticate over HTTPS by using either a basic authentication method (username + password) or a personal access token.
Notes:
  • The authentication using personal access tokens has been tested with GitHub and GitLab.
  • Bitbucket uses a concept similar to personal access tokens, named app passwords. An app password must be provided as the password for Basic authentication, along with the correct username.
  • As of August 13, 2021, GitHub will no longer accept password-based authentication.

If you have the two-factor authentication (2FA) enabled for GitHub or GitLab, to authenticate over HTTPS, you must generate a personal access token for your profile, and back in the Git Staging view in Oxygen JSON Editor, use the generated token value as the authentication password when asked for your credentials.

If, for example, you have been using a GitHub account but you decide to switch to another GitHub account, you would need to reset your credentials so that you will be prompted for new ones. This is because only one set of credentials for each Git platform/server is stored. To reset your credentials, go to the toolbar at the top of the Git Staging side-view, click the settings icon (a cogwheel), and select Reset all credentials.

Selecting a Working Copy

Click the Browse button to the right of the Working copy combo box to select a working copy from your file system. The selected folder must be a Git repository.

Switching Between Local Branches

To switch between local branches from the Git Staging view, use the Branch combo box. Local branches can also be changed using the Git Branch Manager.

New branches can be created from the Git Branch Manager or from the History table using the Create branch action in the contextual menu.

Stashing Files

A Git stash is a way of temporarily saving the changes you have made to your working copy so that you can continue to use other Git operations in the meantime, and you can then re-apply the stashed changes later.

On the toolbar, there is a Stash drop down menu with a Stash changes action for creating a new stash out of the working copy changed file and a List stashes action that presents a dialog box with the existing stashes. From, the List stashes dialog box, you can also choose to apply or remove a stash.

Creating Tags

Tagging is used to capture a specific point in history, for example to mark a release. A tag is like a branch that doesn't change. You can create tags from the History view contextual menu. In the Ellipsis (three vertical dots) menu on the right side of the Git Staging view's toolbar, there is a Show tags action that lists all the tags. Both local and already pushed tags can be deleted from this dialog box. For tags present only in the local branch, you can choose to push them to the remote repository. The Show tags action is also available in the Git menu from the main menu bar.

Working with Submodules

When cloning a repository that contains submodules, all submodules are initialized and cloned as well. When pulling changes from the remote repository, the submodules are also updated. The update of the submodules when performing a pull operation depends on the Update all submodules after pulling changes from the remote repository option from Options > Preferences > Plugins > Git Client (the option is enabled by default).

When checking out a branch for a parent repository with submodules, the submodules are also checked out at the index in the parent repository to reflect the actual state of the repository at that particular time.

To open and work with a Git submodule, use the Submodules action from the Ellipsis (three vertical dots) menu (on the right side of the Git Staging view's toolbar) and select the desired submodule from the presented combo box. As an alternative, if the submodule is modified and is presented in the Unstaged files area, the Open contextual menu action can be used to open it.

The tooltip of a modified submodule shown in the Unstaged files area presents information about the currently and previously tracked commits.

Showing the Repository History

To show the history, invoke the Show current repository history action from the toolbar of the Git Staging panel (look for the clock icon) or go to Window > Show view > Git History. This opens the Git History view at the bottom of the application.

In the toolbar, you can choose which branches will have the history shown. You have the following options:
  • Current branch - Shows the commits for the current branch, including unpushed local and unpulled remote commits.
  • Current local branch - Shows the commits only for the current local branch, including unpushed local commits.
  • All branches - Shows the commits for all branches (both local and remote), including unpushed local and unpulled remote commits.
  • All local branches - Shows the commits only for local branches, including unpushed local commits.
For each commit in the history table, the following actions are available:
  • Create branch - Used to create a new branch starting from the selected commit. The new branch is automatically checked out by default. To disable this behavior, deselect the Checkout branch option in the Create branch dialog box.
    Tip: To publish a new branch to the remote repository and start tracking that branch, you need to simply push the local branch using the dedicated action from the Git Staging side-view.
  • Create tag - Used to create a new tag on the selected commit. You have the option to push the tag to the remote repository.
  • Checkout - Used to checkout a branch at a specific commit (either in detached head form or by creating a new branch at that commit).
  • Revert commit - Used to create a new commit that reverts all the changes from the selected commit.
  • Reset "[branch_name]" to this commit - Used to undo changes by moving the HEAD of the current branch to the selected commit.
The Git History view presents all the affected resources for each commit in a list, in the bottom-right area. It includes a text filter field at the top that you can use to conduct searches (e.g. by Date, Author, or Commit ID). An included revision graph helps you to understand how commits connect with one another. For each resource, the following actions are available in the contextual menu:
  • Open (available for added and modified resources) - This action opens the selected resource.
  • Open previous version (available for deleted resources) - This action opens the version of the selected resource from before its deletion.
  • Open working copy version (available for added and modified resources) - This action opens the working copy version of the selected resource. It also works if the resource has been renamed in between versions.
  • Reset file to this commit (available for added and modified resources) - This action checks out the selected version of the resource, overwriting its current version. It does not work if the resource has been renamed or deleted in between versions.
  • Compare with previous version (available for modified resources) - This action compares the selected version of the selected resource with the previous one using the Compare Files tool.
  • Compare with working copy version (available for modified resources) - This action compares the selected version of the selected resource with the current one using the Compare Files tool.
  • Compare with each other (available when selecting 2 versions of a single file) - This action compares the selected versions with each other using the Compare Files tool.

Blame

The contextual menu of each unstaged resource contains a Show blame action that opens the selected resource in the main editing area and colors the editor lines with different colors based on the revision information. Selecting a line in the opened editor will highlight the corresponding entry from the history table in the Git History side-view.

This action is also available in the contextual menu of the current editor and of the Git resources from the Project side-view.

Unstaged Files Area

In the Unstaged files area, you will see all the modifications that have occurred in your working copy (files that have been modified, new files, and deleted files) and are not part of the next commit.
  • Various actions are available in the contextual menu (Open, Open in compare editor, Stage, Discard, Show history, Show blame, and more).
  • You can stage files (i.e. move them to the Staged files area) using the actions from the toolbar found above the top-right corner of this area. You can choose between staging all the files, by clicking the Stage all button (double arrow icon), and staging specific files, by selecting them and clicking the Stage selected button (single arrow icon).
  • You can switch between the list view and the tree view by clicking on the Switch to tree/list view button positioned to the right of the staging buttons.

Staged Files Area

In the Staged files area, you will see all the resources that are ready to be committed. The files from this area can be unstaged and sent back to the Unstaged files area. This area has actions similar to those from the Unstaged files area, with the exception of the Show history and Show blame actions that are not available here.

Comparing Changes and Conflict Resolution

At any time, if you want to see the differences between the last commit and your current modifications, you can double-click a file from either the Unstaged files area or Staged files area, and the Compare Files window will appear and highlight the changes.

If the file has a conflict (has been modified both by you and another), Oxygen's 3-Way file comparison feature will show a comparison between the local change, the remote change, and the original base revision.

Committing

After staging the files, on the bottom of the view you can provide a commit message and commit them to your local repository. For convenience, you can also select a previously provided message.

In the toolbar above the Commit message text area, there are a few toggle buttons that affect your commit if they are enabled:
  • Amend last commit - Enabling this option is a convenient way to modify the most recent commit. It lets you combine staged changes with the previous commit instead of creating an entirely new commit. It can also be used to simply edit the previous commit message without changing its snapshot. This action should not be performed on public commits (commits that were pushed to the remote repository).
  • Automatically push changes to remote when committing - If this option is enabled, when a commit is performed, the committed changes are also pushed to the remote repository.

Push/Pull (with Merge or Rebase)

To push your local repository changes to the remote repository, use the Push button from the view's toolbar (up arrow).

To bring the changes from the remote repository into your local repository, use one of the actions from the Pull drop-down menu located on the toolbar (). You can choose between Pull (merge) and Pull (rebase). The invoked action is promoted as the current action of the toolbar button.
Note: When pushing a local branch that does not have a corresponding remote branch, a remote branch will automatically be created with the same name as the local branch.

File Conflict Solving Workflow

After editing a file, committing it to the local repository, and trying to push it to the remote repository, if a warning appears about not being up to date with the repository, follow these steps:
  1. Pull the data from the repository using one of the Pull actions.
  2. In the Unstaged files area, select each conflicted file and resolve the conflicts. You can do this, for example, by opening the conflicted files in the compare editor, either by double-clicking on them or by using the contextual menu action, and then choose what changes you want to keep and discard, and save the document. You can also use the Resolve using Mine, Resolve using Theirs, or Mark as resolved actions from the contextual menu of a resource.
  3. If you choose to use the compare editor, after you close it, the file will be staged automatically and moved to the Staged files area.
At this point, the next actions depend on which Pull action was chosen:
  • Pull (merge):
    1. When all the conflicts are resolved and no more files are left in the Unstaged files area, the changes can be committed.
    2. Enter a message and commit. You will now have new changes to push.
    3. Push the changes to the remote repository.
    Note: You can abort the merge by clicking the Abort merge button. This will revert the repository to its previous state prior to the pull attempt.
  • Pull (rebase):
    1. When all the conflicts are resolved, click the Continue rebase button.
    2. Push any outgoing changes.
    Note: You can abort the rebase by clicking the Abort rebase button. This will revert the repository to its previous state prior to the pull request.

Working with Large Files in Git

Git repositories are designed to track changes to text-based files, such as source code, and are optimized for small file sizes. Large binary files (such as image or video files) can slow down the Git repository and make version control difficult. Git's Large File Storage (LFS) provides a solution to this problem by efficiently storing and managing large files outside of the repository.

To start using LFS, follow the instructions at https://git-lfs.com/. Once you have installed LFS and defined the tracked large files in your repository, large files will be automatically detected and handled properly.
Warning: If you are using a proxy, you need to set the HTTPS_PROXY environment variable for git operations that involve LFS for it to work correctly.

Setting the HTTPS_PROXY environment variable on Windows from the command line

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

The Project View and the Current Editor

For resources from Git repositories, this add-on also contributes a variety of actions in the contextual menus of the Project side-view and the current editor (Text and Author modes). These actions include: Show history, Show blame, Git Diff (only in the Project view), and Commit (only in the Project view).

Git Branch Manager

To show all the local and remote branches, click the Show Git Branch Manager button on the toolbar of the Git Staging panel (look for the branches icon) or select Git Branch Manager from Window > Show view. By default, the Git Branch Manager is presented to the right of the editing area.

The Git Branch Manager side-view displays all the branches as a tree. The tree can be filtered using the text field at the top of the panel and you can reload the information by using the Refresh action. When hovering the cursor over a branch name, a tooltip is displayed that provides information about the last commit performed on that branch (such as the author and the date of the commit).

The following actions are available in the contextual menu for each local branch:

  • Checkout - Checks out the selected branch and switches the local repository to the selected branch.
  • Create branch - Creates a new branch using the selected branch as the starting point. The new branch is automatically checked out by default. To disable this behavior, deselect the Checkout branch option in the Create branch dialog box.
    Tip: To publish a new branch to the remote repository and start tracking that branch, you need to simply push the local branch using the dedicated action from the Git Staging side-view.
  • Merge "SELECTED_BRANCH" into "CURRENT_BRANCH" - Merges all the changes from SELECTED_BRANCH into CURRENT_BRANCH.
  • Squash merge "SELECTED_BRANCH" into "CURRENT_BRANCH" - Merges all the changes made on the SELECTED_BRANCH since it diverged from the CURRENT_BRANCH, on top of the CURRENT_BRANCH, and it records the results in a new commit.
  • Delete - Deletes the selected branch.

For the remote branches, the Checkout branch action checks out the selected branch and creates a local branch from the selected remote branch.

Preferences

The Git Client add-on contributes a preferences page to Oxygen JSON Editor. To access it, go to Options > Preferences > Plugins > Git Client or Git(Menu) > Settings > Preferences or click the Ellipsis menu button from the toolbar of the Git Staging view and select Preferences. This preferences page includes the following options:

  • When detecting a Git repository inside a newly opened project - This determines what happens to the current working copy when a project that contains a Git repository is opened in the Project side-view. You can choose between:
    • Always switch to the new working copy
    • Never switch to the new working copy
    • Always ask (default value)

  • Notify me about new commits in the remote repository - When this option is selected, Oxygen JSON Editor will show notification messages when it detects that new commits have been pushed to the remote repository. By default, this option is not selected.

  • Update all submodules after pulling changes from the remote repository - If this option is selected, when a repository is updated using the Pull operation, all sub-modules are updated as well. This option is selected by default.

  • Detect and open Oxygen projects (.xpr) from opened working copies - If this option is selected (by default, it is not selected) and a working copy that contains one or more project files (.xpr) is opened:
    • If one .xpr file is found, it will be opened automatically.
    • If more than one .xpr files are found and none of them are opened, a dialog box will appear where the .xpr can be selected.

  • Validate each file before commiting - When this option is selected, each file to be committed will be validated individually. If validation problems are detected, the commit operation will be stopped and a dialog box will appear informing you that the problems can be viewed in the "Results" area (in the "Git pre-commit validation" tab). If the Reject commit when validation problems occur option is selected (the default state), the dialog box will include a Commit anyway button that allows the commit operation to be completed even if validation issues have been found.

  • Global Options/Project Options - If you select Project Options, the settings are stored in the project file (.xpr) that can easily be shared with other users.
Under the preferences page, there is the "SSH Connections" page, which includes the following options:
  • Use SSH agent - when this option is selected, the selected SSH agent support is used to benefit from the SSH keys already stored in it. On Linux, OS X, and BSD, the only agent communication mechanism supported is the usual communication via a Unix domain socket. On Windows you can choose between:
    • Pageant
    • Win 32 Open SSH(default value)

Editor Variables

The Git Client contributes the following editor variables:

  • ${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 (e.g. dev).
  • ${git(full_branch_name)} - The full name of the current branch (e.g. refs/heads/dev).

Resources

For more information about the Git Client add-on, as well as details regarding other popular add-ons that extend the functionality of Oxygen JSON Editor, see the following webinars/presentations/articles: