Re: DITA and Git: Minimizing merge conflicts #version-control #change-management

For an Oxygen-using client that uses git on the back end I implemented a custom set of actions using the Oxygen git plugin as my code base that automates all the git actions for users, including creating feature branches, checking for updates, letting users know that their local branch is out of date, and so on.

This was not a trivial effort but it wasn't that hard either. Unfortunately this was a work for hire so I can't share the code, but it was mostly an exercise in figuring out how to automate the git actions and do the necessary error handling, as well as my personal struggle with how to do UI programming in Java and Oxygen (not something I had done much of to that point).

But looking Kris' initial question, I think the key is the amount of time that feature branches go without being updated to reflect the develop branch--doing that frequently will avoid most merge conflicts and limit the ones that do occur to hopefully clear reasons. As long as authors are not simultaneously working on the same topics or maps or inadvertently modifying files they shouldn't (for example, by reformatting the markup in a file that hasn't had its content otherwise changed) there should not be many merge conflicts. But ensuring this requires communication among the team members.



Eliot Kimber

On 12/18/19, 6:52 AM, "Kristen James Eberlein" < on behalf of> wrote:

Thank you, Chris, Alastair, and Jean-Noël for your feedback.
I do want to set some additional context here:

* I am familiar with and comfortable with Git, although it is
new to the technical writers on this project. (And perhaps
frightening to the manager.) I started using Git when the
DITA-OT project moved to it from SVN, and I'm still grateful for
all the help that Jarno Elovirta, Robert Anderson, and Roger
Sheen gave me as I learned Git.

* Yes, good practices for Git are just standard, good software
development practices: Keep feature branches discrete; update
feature branches by pulling from the current development
repository frequently; commit thoughtfully and frequently with
good commit messages, so that cherry picking is a possibility.

* For this project, the technical writers are using oXygen, and
we can control formatting through common project files to reduce

That said, version control with Git can have a steep ramp-up for
technical writers. Any thoughts about how to best minimize that?
Useful resources?
And how to best plan a process for the scenario in which a
writer wants to merge some (but not all content) from a feature
branch into the development branch? In the absence of
granular commits with descriptive commit messages, cherry picking
is a not a realistic option.
So far I've handled this manually, by asking the writer for names
of the files that she wanted merged; merging them into a local
copy of the development branch; resolving merge conflicts and QA
errors (errors in DITA source, spelling); and eventually merging
into the development branch.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting <>
+1 919 622-1501; kriseberlein (skype)

On 12/18/2019 6:13 AM, Alastair Dent

Using Git requires a change in thinking.

All authors need to abandon the thoughts of 'check out',
'check in', 'lock'. Those don't really apply to git.
New concepts that are absolutely essential to learn are
'remote', 'origin', 'branch'.

When an author pulls a repository ( pulling a copy of the
main repository), they are creating a local repository. Their
work will take place in this repository. Usually, good
practice is to create a local branch for new work. *Always*
update your local repository before starting a new piece of
work (fetch and pull the latest updates from the origin).

When working on DITA files, the files are numerous and
small. It is unusual for two authors to both edit the same
file at the same time. Frequent updates and pushes are the way
to work.

This is no different to programmers working on code.

Join to automatically receive all group messages.