Git Branch Manager

[mross]

We have been using the Git client add-on and the team is largely accepting of the tool with these exceptions:
* they can't merge branches
* they can't stash uncommitted changes as they switch between branches

We're having to use BitBucket git to merge branches with pull request and the team wants to be able to do all git commands in Git Staging and Git Branch manager.

Question: Does Oxygen have these features in future roadmap?

[sorin_carbunaru]

Hello,

I'm glad to hear to are using the add-on.

Yes, we do plan to implement these 2 features in the near feature. If all goes well, perhaps they will be available in a few months.

All the best wishes,
Sorin Carbunaru
Oxygen XML Editor

[mross]

This is great to hear!

In Bitbucket git, I create a pull request from source branch to destination branch. I get a merge conflict. Bitbucket shows me the conflicting file.

Bitbucket instructs me to checkout the source branch, and on that branch run git pull origin <destination branch>. Now the conflicting file has the conflict markers <------HEAD around conflicting text.

In Oxygen Git Staging, I verify I am on the source branch and do a refresh, now I see the conflicting file in unstaged area and the right-click options to Resolve Conflict are available.

My question is: How can I get the source branch in Git Staging to obtain the merge conflict information from the Bitbucket pull request without having the writers use the command line to run the command: git pull origin destination?

Any advice is appreciated!

[mross]

In this help topic https://www.oxygenxml.com/doc/versions/ ... addon.html, under "File Conflict Solving Workflow", what does "Mark as Resolved" do? How is that different that using mine or theirs?

[sorin_carbunaru]

Hello!

1. You can't pull from another branch using our Git Client Add-on. At least not yet. We have an improvement request already recorded and I added your vote for it.

An alternative would probably be to create an external tool that runs "git pull origin ${ask()}", where "${ask()}" is an Oxygen editor variable that would allow you to provide the name of the branch.

2. "Mark as resolved" uses the current version of your document as the resolved one. This is useful when you manually resolve the conflict by editing the file. After you finish the editing, you can use "Mark as resolved" to resolve the conflict. In other words, you use this action when you need a sort of hybrid between your changes and their changes.

Best wishes,
Sorin Carbunaru
Oxygen XML Editor

[chrispitude]

Stash and restore support would be great! But it should be implemented with a thoughtful and intuitive graphical interface. Git is already challenging for less technical writers. Part of the value Oxygen delivers is to make complex technologies accessible to writers.

My company is a software company. We release software (and thus documentation) every three months. In Git, we have release branches that correspond to each calendar release cycle.

This approach allows writers who finish early to jump to the new branch, and writers who are delayed (by their product teams) to continue working. For example, consider three writers A, B, and C, where A finishes their release work early and C is delayed:

image.png (18.49 KiB) Viewed 4890 times

We have been using this release branch methodology for 1.5 years and it works well. Occasionally, a retroactive change to older an release is required. When this occurs, I perform a cascade of branch merges from old to new to propagate the changes.

Our repo is hosted on an internal Gitlab instance. When a writer is ready to move to the next release branch,

1. They file an "old-to-new branch" merge request on the repo's Gitlab web page, then wait for a completion email from Gitlab.
2. I receive and complete the merge request.
3. They receive the completion email, pull the "new" release branch in Oxygen, and continue working in that branch.

Step 2 (completing the merge request) is the tricky part. If the merge request page indicates there are no conflicts, I click the green "Merge" button, which completes the merge and emails the writer. (Super easy!) But if the merge request page indicates conflicts, then I clone the entire repo in a linux environment, do my own manual merge and resolve the conflicts by hand, and commit the merge results manually. When Gitlab sees my pushed merge commit and notices that it satisfies its own merge request, it auto-completes its own request and notifies the writer.

If Oxygen provided GUI functionality to perform branch merges directly in the tool, I hope there is some way to disable or hide by default. Otherwise, I worry that a writer could perform/commit/push a lot of accidental multiple-branch damage very quickly, and once others pull those changes from the server, we are in for a world of trouble.

[sorin_carbunaru]

Hi Chris,

1. Right now, we are thinking about creating a dialog for the stashes. We thought that usually writers would probably not have too many stashed changes, and a separate side-view might be too much for a few items. On top of that, the Git Client already contributes 3 side-views... Therefore, we incline towards creating a dialog that will present the list of stashed changes. For each item the users will be able to see a diff and apply or delete the changes. Of course, there will also be an action for stashing the current working-copy changes. Any feedback on this is welcome.

2. I understand your fears about the "Merge" action... One step that we took was to avoid accidentally invoke the merge action, by showing a confirmation dialog box. Now, in regards to some additional steps, I'm not sure what to say... Perhaps we could make use of a custom system property. You could set it when launching Oxygen (for example, in the .bat or the .vmoptions file). When the system property has a certain value, we can remove the "Merge" action. I wouldn't add an option in the UI...

Looking forward to your always-high-quality feedback .

Best wishes,
Sorin Carbunaru
Oxygen XML Editor

[chrispitude]

Hi Sorin,

Thanks for putting continued development into this plugin!

For Git stashes, I think a dialog box is a good approach. It won't be an often-invoked operation. (A Google search for "Git stash icons" shows various fun potential button ideas?) When at least one stash exists, I suggest writing that number over the button (as with pending pushes and pulls) as a visual reminder that content exists there.

Stashes work with staged files, so perhaps a stash icon on the "Staged files" area (to the left of the two unstage buttons) with pertinent actions in a drop-down menu would work? This reinforces the intuitive model of saving/restoring files to that dialog box.

I don't have strong opinions on how the button(s) should be structured. Should there be multiple buttons (push, apply, pop, delete) arranged horizontally? Should there be a single button that lists stashes first and push/apply/pop/delete as a submenu for each one, or should it list push/apply/pop/delete operations first, then prompt for the stash to operate upon in dialog boxes as needed? I am happy to put more thought into this (and maybe ask some of our writers) if you would like more consideration in this area.

I feel like pushing a new stash should require the user to enter a user-defined label. I am not sure it is a good idea to allow unlabeled stashes to accumulate when the user audience is nontechnical (too easy to accept the default, too easy to let things accumulate without understanding/reviewing/housecleaning).

For merges, I don't think a system property would solve the problem for us unless it was an "opt-in" property that enabled the feature. Somehow, I feel merges should be off-by-default to avoid novice users from potentially inflicting unintentional damage across branches.

Perhaps another option is to provide an option to enable/disable the merge button (off-by-default) in Preferences > Plugins > Git Client. Although this setting would be accessible to novice users, they would lack the knowledge and ambition to mess with it.

[sorin_carbunaru]

Hi Chris,

It's enough to know that we are not the only people thinking that a dialog box would be a good option for the Stash support. As for the rest of the GUI details, we will analyze them internally. Thank you for your help!

In regards to branch merging, we were wondering, do you use Oxygen projects for your work? Perhaps we could add a new option in the Git Client preferences page, and you could set it to the desired value for each project. Setting the Git preferences at the project level would require some extra work, but we were planning to do this for the next release anyway.

All the best,
Sorin

[chrispitude]

Hi Sorin,

Not only do we use a project file, but we also have a request for the project file to assist in deploying required plugins and their desired settings, as described here:

Site-Wide Deployment of Addons

The goal is for any writer to be able to do a Git clone of our repo, then immediately have the repo-configured authoring environment ready for use. This could be for new hires, or writers getting replacement laptops, or even writers using a temporary loaner laptop from IT while theirs is repaired.

Thinking out loud some more... the drawback to this approach is that my .xpr file would differ from everyone else's, and would thus always show up in the Git Staging view waiting for me to accidentally commit it. I can work around this by only changing my plugin settings when I need to merge a branch. Or maybe both mechanisms are best - a project-level plugin setting to control the default for a Git project, then a system-level setting that takes precedence for administrator-like people?

[sorin_carbunaru]

Hi Chris,

We had a discussion during a review meeting and the conclusion was that it's a bit weird to add an option to deactivate such an important feature. When working with branches, merging them is what completes the workflow. Of course, you can also rebase or create a pull request...

Is working with protected branches an option for you? This is not a Git feature, but a Git-host feature instead (e.g. GitHub, GitLab). This way you may not allow the writers to merge without a review. Or perhaps you can create a workflow that uses pull requests. Of course, you would need to instruct the writers not to use the Merge action in Oxygen. One positive thing is that the action requires a confirmation before it is performed, therefore nobody will merge branches by accident.

All the best,
Sorin

[xephon]

This is an interesting discussion. We’ll implement a similar setup with technical writers who are neither familiar with XML nor with Git. Because the Git addon is so limited in functionality, we’ll define a specific role, something like “release manager”, who is good in Git. A technical writer will only find a remote branch for his specific ticket and pull and push to and from this branch. The expert will take care for merging and so forth after the technical writer had sent a pull request. Technical writers won’t be allowed to commit to the main branch. The expert will merge stuff from other branches, if needed.

[sorin_carbunaru]

Hi Stefan,

Could you tell us what features you and your team miss the most in our Git Client? This would be very helpful to us. Also take a look at what will be available in v2.6.0 (scheduled for the end of this month or the beginning of the next one): https://github.com/oxygenxml/oxygen-git ... /addon.xml. Note that the list is still work in progress. We also plan to include some support for stashes and tags in the next release.

Looking forward to your reply.

Best wishes,
Sorin Carbunaru

[alex_jitianu]

Hello,

In the newly released version 3.0.0 you can save the uncommitted changes into stashes, reapply or delete the stashed changes. A new Merge "SELECTED_BRANCH" into "CURRENT_BRANCH" action was also added in the contextual menu for local branches in Git Branch Manager.

Best regards,
Alex

[chrispitude]

We had a discussion during a review meeting and the conclusion was that it's a bit weird to add an option to deactivate such an important feature. When working with branches, merging them is what completes the workflow. Of course, you can also rebase or create a pull request...

Is working with protected branches an option for you? This is not a Git feature, but a Git-host feature instead (e.g. GitHub, GitLab). This way you may not allow the writers to merge without a review. Or perhaps you can create a workflow that uses pull requests. Of course, you would need to instruct the writers not to use the Merge action in Oxygen. One positive thing is that the action requires a confirmation before it is performed, therefore nobody will merge branches by accident.

Hi Sorin,

Unfortunately, Gitlab's "Allowed to merge == No" protected branch setting does not prevent locally-performed merges from being pushed, as described here:

https://gitlab.com/gitlab-org/gitlab-fo ... sues/60330

https://gitlab.com/gitlab-org/gitlab-fo ... sues/50417

I confirmed this both in Oxygen's Git client and in command-line Git in linux. From the issue log, apparently this is because "Allowed to push == Yes" takes precedence over "Allowed to merge == No", thus allowing downstream merge commits to be pushed upstream to Gitlab.

So, I will need to rely on education to prevent users from performing local merges. Our users are very aware of what merges do (we use release branches and regular merges performed by admins), so it's quite possible that a user might want to try to do something themselves and make a big mess in the process.

Let's hope not.

[sorin_carbunaru]

1. You can't pull from another branch using our Git Client Add-on. At least not yet. We have an improvement request already recorded and I added your vote for it.

Hi,

Just to update this thread, in the recently released version 5.4.0 of the Git Client it is now possible to pull the changes from another branch than the one being tracked.

All the best,
Sorin Carbunaru
Oxygen XML Editor