What about Git support?
-
- Posts: 384
- Joined: Mon May 09, 2016 9:37 am
Re: What about Git support?
Post by sorin_carbunaru »

-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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
- git_xpr2.PNG (16.64 KiB) Viewed 10880 times
- git_xpr3.PNG (37.87 KiB) Viewed 10880 times
Re: What about Git support?
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
<oXygen/> XML Editor
http://www.oxygenxml.com
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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.
----
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!
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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
Re: What about Git support?
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
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: What about Git support?
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
<oXygen/> XML Editor
http://www.oxygenxml.com
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
Re: What about Git support?
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.
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
Hmm, interesting. Has anyone tried making precommit hooks with WSL (Windows Subsystem for Linux) in Windows 10?GHogarth wrote: ↑Thu Jan 09, 2020 6:07 pm 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.
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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?
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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'
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'
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?
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
-
- Posts: 384
- Joined: Mon May 09, 2016 9:37 am
Re: What about Git support?
Post by sorin_carbunaru »
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.
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
-
- Posts: 384
- Joined: Mon May 09, 2016 9:37 am
Re: What about Git support?
Post by sorin_carbunaru »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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
[X] Ignore local changes to project file
option so that writers could apply and unapply (--no-skip-worktree) this property in their local repos.
-
- Posts: 384
- Joined: Mon May 09, 2016 9:37 am
Re: What about Git support?
Post by sorin_carbunaru »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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.
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
Hi Sorin,sorin_carbunaru wrote: ↑Wed Mar 11, 2020 4:45 pmI 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.
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.
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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.)
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
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.
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
If multiple-choice is an option, you could have ignore, ask, always choices. This would allow each customer to choose what is best.
-
- Posts: 818
- Joined: Thu May 02, 2019 2:32 pm
Re: What about Git support?
Post by chrispitude »
Can you share more details on how you implemented your precommit hook?GHogarth wrote: ↑Thu Jan 09, 2020 6:07 pm 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.
-
- Posts: 968
- Joined: Wed Nov 16, 2005 11:11 am
Re: What about Git support?
Post by alex_jitianu »
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
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service