What about Git support?

[sorin_carbunaru]

I'm glad to hear your colleagues love the Git integration ! It feels good when the clients are happy with your work.

[chrispitude]

I just installed the latest v2.0.0 update of the Git plugin. There is support for rebase-pulling - I'm excited to try it out!!

A quick question to everyone... We have our *.xpr Oxygen project file stored in our Git repository, so that (1) pulling the Git repository down creates a ready-to-use project, and (2) we can share project-wide settings like hotkeys and transformations.

However, we're finding that some day-to-day actions cause a user's *.xpr file to get modified. For example, let's say I change the map context in the DITA Maps Manager:

git_xpr1.PNG (21.23 KiB) Viewed 10880 times

This causes the project file to show up as a changed file:

git_xpr2.PNG (16.64 KiB) Viewed 10880 times

And when I look at the differences, the only change is the map context setting:

git_xpr3.PNG (37.87 KiB) Viewed 10880 times

How are others handling modifications to shared *.xpr project files in a Git flow?

[Radu]

Hi Chris,

Indeed Oxygen auto-saves various settings at project level. Besides the root map setting another setting we auto save at project level is the association between an opened map and a publishing scenario and we have users having problems also with this.
Honestly I'm not sure how to best handle this on our side. I mean, saving the root map setting at project level is useful, if you give the XPR to somebody new they just need to open the XPR and they will have the root map properly set.
At some point we wanted to add a special setting for the XPR project, something like "[ ] Lock project settings". This setting would be checked by you (the admin) before committing the XPR on GitHub. And for anybody opening the XPR, Oxygen would no longer save settings at XPR level. But what would happen if they change the root map? Would the setting get auto saved to Oxygen's global options?
Or if you are never interested in imposing the root map, maybe we could have particular settings like "[ ]Save Root map settings at project level" or "[ ]Save scenario associations at project level". And you could uncheck both these checkboxes (which would add some flags inside the XPR), then share the XPR with others...

Regards,
Radu

[chrispitude]

Hi Radu,

For smaller projects, it's definitely useful to store the root map and scenario associations in the project file. Like you say, any user can obtain and open the project, and they will have sensible default behaviors ready for them.

I believe this becomes less ideal when there are multiple users or multiple root maps (or both).

Let me think out loud here...

Multiple root maps

When I work with multiple root maps simultaneously, for me the concept of a global root map setting becomes more hindering than helpful. It would be nice if each editing window remembered the context in which it was opened. There are various places where the filename is shown (main window bar, bottom status bar, tooltip for editor tab) and these could display the root context in a suffix for clarity.

For example, let's say I have a shared topic S in books A and B. If I open S from A's map and S from B's map, each of these editing windows should remember its root context and resolve references accordingly. If I copy a figure from the S-from-A or S-from-B window then paste-special as a keyref link into another topic editing window T, the reference should be constructed using the keydef/scope information from either bookmap A or bookmap B, respectively.

Would this editing window root-context completely subsume the need for the simpler global root context? I am not sure, because I don't know what non-editing features the global root map setting affects.

Multiple scenario associations

The situation is less clear to me when there are multiple users and multiple writers. Perhaps it would be useful for two levels of association:

• The project administrator sets up all associations that might be useful when working in the project, and
• The users can select their own associations within the set configured by the administrator.

This would work in conjunction with my other filed feature request, for the "Apply Transformation Scenario(s)" button to be a drop-down that lets you run a single transformation from the associated set, thus preventing the need to change the associated net.

----

For both the root maps and scenario associations, I am just thinking out loud. These ideas are more complicated than having an option to lock the project file and push any varying settings to the user's global file. They might have usability or technical issues I haven't considered.

I hope other users can share their thinking too!

[chrispitude]

The situation with our shared project file became unworkable. Despite telling everyone not to include it in commits, it still accidentally got staged/committed/conflicted.

For now, we have a MASTER project file in the repo, then each writer copies it to their own working copy. I added the following lines to our .gitignore, which ignores any project file except our master file:

Code: Select all

*.xpr
!our_books_MASTER.xpr

This means that writers don't get updates to the project file automatically, but we can work with that for now.

[Radu]

Hi Chris,

For your feedback about remembering from what DITA Map context the topic was opened, we have issue with ID EXM-43179 registered. I do not have a timeline estimate for it.
For the problem with the XPR being often modified, I think right now your approach of having a master XPR is the right one. I registered issue EXM-44587 for it and in this case we are starting to better understand what we need to do in order to allow you the flexibility to choose if certain settings should be saved at project level or not. If we manage to fix it we'll update this forum thread but I cannot guarantee a fix in the Oxygen 22 release, maybe in the minor 22.1 release which will be in Spring 2020.

Regards,
Radu

[Radu]

Hi Chris,

As an idea related to the changed XPR, we have an end user who created a script which is run every time someone pulls and which updates the tech writer's XPR from the master XPR:

viewtopic.php?p=56230#p56230

Regards,
Radu

[havip]

Still no plan for Git support?

[alex_jitianu]

Hi,

Well, there is actually Git support for awhile now. It comes in the form af an add-on and to install it you need to:
1. Go to Help->Install new add-ons...
2. If you are running Oxygen version 21.1 just select Default Update Site from the top combo. If not, paste this URL: https://raw.githubusercontent.com/oxyge ... /addon.xml
3. Check the Git Support add-on and follow the install procedure

Best regards,
Alex

[chrispitude]

havip, this Git plugin has become one of the most-loved features of Oxygen in our team. Give it a try!!

[GHogarth]

Important note: (thanks to alex_jitianu)
The Oxygen's Git plugin is based on the JGit library, which supports at least the precommit Git hooks.
If you are running on Windows, you need to:
1. Install Cygwin. You'll need to nstall the Git packages in Cygwin too, because the hook scripts want to execute git command.
2. Add the Cygwin bin folder (e.g. cygwin64\system\bin) to the Windows PATH environment variable.

[chrispitude]

Important note: (thanks to alex_jitianu)
The Oxygen's Git plugin is based on the JGit library, which supports at least the precommit Git hooks.
If you are running on Windows, you need to:
1. Install Cygwin. You'll need to nstall the Git packages in Cygwin too, because the hook scripts want to execute git command.
2. Add the Cygwin bin folder (e.g. cygwin64\system\bin) to the Windows PATH environment variable.

Hmm, interesting. Has anyone tried making precommit hooks with WSL (Windows Subsystem for Linux) in Windows 10?

[chrispitude]

Hi Alex,

When I create a new branch on the remote Gitlab server, how do I get the Git plugin in Oxygen to show it in the branch dropdown list?

[chrispitude]

In researching this further, I found that remote branches aren't automatically pulled down; you must explicitly create a local branch and set it to track a remote branch:

Code: Select all

$ git checkout --track origin/ani-test
Branch 'ani-test' set up to track remote branch 'ani-test' from 'origin'.
Switched to a new branch 'ani-test'

This makes sense, as we wouldn't want *all* the branches we keep on the server (release branches and such) to be pulled down to everyone's repos!

I also learned that this is a common enough operation that if you attempt to checkout a local branch that doesn't exist *and* matches the name of a remote branch, it's a shortcut to do the same thing:

Code: Select all

$ git checkout ani-test
Branch 'ani-test' set up to track remote branch 'ani-test' from 'origin'.
Switched to a new branch 'ani-test'

So if the Git plugin had an additional "<new branch>" option in the branch dropdown that prompted the user for a name, then we could create a new local branch (if a unique name) or a local-tracking-remote branch (if a same-named branch exists on the server).

Or we could provide a simple CLI to JGit where they could type the "git checkout <branch>" command, and/or other branch maintenance/deletion commands?

[alex_jitianu]

Hi Chris,

Our plugin only allows switching between local branches, like you've already discovered. We do have an issue recorded to allow also checking out remote branches which means creating a local branch and link it to the remote one with the same name. I've increased its priority and we will let you now when we finally get the manpower to do it.

Meanwhile, since you mentioned CLI, if the users also have a command line git client on their systems, you can configure External Tools to invoke the git commands that check out branches. You can use ${ask} variables to get the name of the of the branch from the user.

Best regards,
Alex

[sorin_carbunaru]

Hi Chris,

With the recently released Git Client 2.1.0 you should see a busy cursor while the commit is performed.

All the best,
Sorin C.

[chrispitude]

Would anyone else want to see an "auto-pull" feature that would automatically pull remote updates when available? In find that in Git, the longer you go without pulling, the more you are asking for trouble!

[sorin_carbunaru]

Hi Chris,

I haven't seen a Git client that automatically pulls from the remote, at least not by default. I don't know if there is a Git client that offers such an option.

To be honest, I don't know if this would be a great idea, as it would also bring unwanted changes. Imagine a team member commits something that breaks the project. You wouldn't want to pull that change, but wait until it is fixed, and only then pull the changes...

We actually perform an automatic fetch, so you will become aware of the new changes that are available by seeing the pushes counter increase on the Pull button.

Sorin Carbunaru
oXygen XML

[chrispitude]

You are right. This would not be dangerous in our team because writers tend to own different books in their entirety, but a more collaborative project could run into trouble.

On another topic, I find that we are still occasionally having issues with writers committing modified *.xpr Oxygen project files from their local repos back to the server. Sometimes it's because they go poking around in Options > Preferences and change a project-level setting, and other times it's when I push a new *.xpr project file from the server, but then Oxygen writes its current (old) *.xpr file out after a Pull and then sees that as modified.

Git has a --skip-worktree feature designed to handle the case where you want to ignore local changes, but still permit the server to push upstream updates down:

https://compiledsuccessfully.dev/git-skip-worktree/

For example,

Code: Select all

git update-index --skip-worktree snps_books.xpr

Unfortunately this setting must be applied *at* the local repos, and there's no command-line Git client on our writers' laptops. I wish the Git client had a configuration window where we could have a

[X] Ignore local changes to project file

option so that writers could apply and unapply (--no-skip-worktree) this property in their local repos.

[sorin_carbunaru]

Hello Chris,

I created EXM-45209 related to the XPR problem. Meanwhile, perhaps you could ask the writers to add the XPRs to ".gitignore", with you being the only one not doing this... By the way, in oXygen 22 there is a "Project Level Settings" preferences page where you decide to not save certain options at the project level if you don't need to.

Best wishes,
Sorin Carbunaru

[chrispitude]

Hi Sorin,

Thanks! We are using the Project Level Settings and it helps tremendously in preventing unwanted *.xpr modifications. Unfortunately there are still cases where it gets modified by nosy users or tool behaviors we don't yet understand.

I did try the .gitignore approach but it did not solve the problem. If I can reproduce what its limitation was, I will report back here.

[chrispitude]

I haven't seen a Git client that automatically pulls from the remote, at least not by default. I don't know if there is a Git client that offers such an option.

To be honest, I don't know if this would be a great idea, as it would also bring unwanted changes. Imagine a team member commits something that breaks the project. You wouldn't want to pull that change, but wait until it is fixed, and only then pull the changes...

We actually perform an automatic fetch, so you will become aware of the new changes that are available by seeing the pushes counter increase on the Pull button.

Hi Sorin,

We discussed some ideas about this today.

Our writers coming from Perforce, which allows files to be locked so others can't modify them. Git doesn't have a safety net like this.

With Git, the primary concern is that (1) there's an unpulled change lurking in the fetch list, and (2) a writer starts editing that file. It would be great if we could detect when both of these conditions are true and pop up a dialog box notifying the user and providing the opportunity to do a pull before they start editing the file and invite the potential for conflicts.

It's also possible that the file is already being edited when it appears in the change list, where (2) begins before (1). In this case, it's still good to pop up the dialog box and provide the information to the writer as soon as possible.

Ideally this check should apply to any kind of file that can be opened and edited - including the DITA Maps Manager.

[alex_jitianu]

Hello Chris,

I understand their concerns, but for these checks to work, the other writer changes need to be pushed in the remote. What I'm saying is that it might just give them a false sense of security. Again, like you mentioned the ratio of success probably depends on the number of writers and their editing frequency.

In general, git conflicts aren't that difficult to resolve. Most of the times conflicts are resolved automatically when pulling and when there are actually conflicts to resolve, I find Oxygen's 3-way diff to be quite helpful in understanding what's happening. Did you get a change to show it to the team?

I will add a feature request for such a behavior, but we will have to discuss it and decide its priority. By the way, the plugin is open source so, if you have the resources, you can implement this feature yourself. I'll be more than happy to provide some hints and starting points on how this can be done.

Best regards,
Alex

[chrispitude]

For the most part, we haven't had problems. We haven't even had very many conflicts, and I have demonstrated the 3-way diff feature on a few occasions.

But we have a large writing team, many of them nontechnical. Despite repeated reminders, some go a week or more without doing a Pull, and that has been causing some issues in our multi-writer books.

(It's great that the plugin is open-source, but unfortunately I lack the Java expertise to even begin to contribute on that level! I wish I could.)

[alex_jitianu]

Hi Cris,

I'll add a note to also discuss the possibility of an _Automatic pull_ option. Perhaps one that will pull changes only when the local repository doesn't have any changes to push. Like my colleague Sorin mentioned, we already to an automatic fetch so changing it into a pull is not that difficult. It's the implications that we are worried about and we will need to discus.

Best regards,
Alex

[chrispitude]

Hi Alex,

We had a writers' meeting yesterday and one of the topics was Git and the mechanics of push/pull/commit and conflict resolution. I mentioned the idea of doing an auto-pull whenever the pull would complete without conflict, and there was quite a bit of interest in this.

[alex_jitianu]

Hi Cris,

We had a few talks regarding this issue, but we didn't yet agree to a solution. Do you think that a "Warn me if I'm behind" option would help? Instead of automatic pull, the user sees a notification that he is behind the remote repository and he'll have the option to pull right in that dialog.

Best regards,
Alex

[chrispitude]

Hi Alex,

If multiple-choice is an option, you could have ignore, ask, always choices. This would allow each customer to choose what is best.

[chrispitude]

Important note: (thanks to alex_jitianu)
The Oxygen's Git plugin is based on the JGit library, which supports at least the precommit Git hooks.
If you are running on Windows, you need to:
1. Install Cygwin. You'll need to nstall the Git packages in Cygwin too, because the hook scripts want to execute git command.
2. Add the Cygwin bin folder (e.g. cygwin64\system\bin) to the Windows PATH environment variable.

Can you share more details on how you implemented your precommit hook?

[alex_jitianu]

Hi,

I wrote a blog post about my experiments with Git client-side hooks and DITA publishing pipelines. In case it helps, here it is: Using Git client-side hooks to run DITA publishing pipelines

Best regards,
Alex