[GNC] Risks of merging xml save files

[Jim DeLaHunt]

Hello, Ray, and welcome to GnuCash!

On 2026-08-31 20:41, Raymond Maass wrote:
> Hi, all.
>
> Loving Gnucash -- thanks so much for all the development and maintenance to
> help make it what it is.
>
> TL;DR -- Are GUID's for elements (e.g. transactions/splits) in the
> xml-formatted save files generated and used such that they are required to
> be anything other than simple unique identifiers?
My partially-informed answer is No. I have looked at the GnuCash code a 
little bit, and I have yet to see any indication that GUID values have 
any meaning apart from being unique values. I can't give a definitive 
answer, because I have not read through all the code. There are 
developers monitoring this list who probably could give a definitive 
answer. I am not one of them.
>   I'm not sure if this
> makes sense, but I'm worried that, in addition to being unique identifiers,
> they may also serve as some sort of check-sum for consistency like I
> believe git commits do.
The string of digits and letters associated with git commits are 
"digests", not globally unique identifiers. If you and I have identical 
files, and we each compute a digest for our file, then our digests will 
be identical. If you change your file by one character, your digest will 
change completely. If I make the same one-character change to my file, 
then I will get the same digest you did.  By contrast, if you and I run 
identical code to generate GUIDs, we will come up with different values. 
So, digests are not GUIDs. They behave differently and have different 
purposes.
> A few more details:
> I'd like to be able to have my wife and me both able to interact with our
> joint gnucash file via a hosted git repository as a way to
> (a) track history with a bit more detail than the auto-generated backup
> files
> (b) allow us to both work on the same file
>
> So far, I set gnucash on our two separate computers to each save as xml
> without compression, making the git diffs quite readable and enabling merge
> conflict resolution to merge changes back into the main branch when
> conflicts arise.

Well, good luck, and it will be interesting to see how far you get with 
that. I am pretty confident that it will fail eventually.

The GnuCash book file is not just plain text, it is XML-structured plain 
text. Git's merging is based on the rules for line-oriented plain text 
files. It ignores the hierarchical structure of XML. Thus I'm pretty 
confident that sooner or later git will merge the two book files in a 
way that results in an invalid XML file. It's a short step from that to 
GnuCash being unable to use the file.

For instance, imagine that your shared GnuCash file originally had a 
structure like:

<transactionList count=2>
      <transaction>transaction "bd496a" data</transaction>
      <transaction>transaction "147f23" data</transaction>
</transactionList>

Note the "count" attribute. It gives the number of <transaction> 
elements within the <transactionList> element. You add a third 
transaction to your copy of the file, like:

<transactionList count=3>
      <transaction>transaction "bd496a" data</transaction>
      <transaction>transaction "147f23" data</transaction>
      <transaction>transaction "00fade" data</transaction>
</transactionList>

and imagine that your spouse adds a different transaction their copy of 
the file, like:

<transactionList count=3>
      <transaction>transaction "bd496a" data</transaction>
      <transaction>transaction "147f23" data</transaction>
      <transaction>transaction "beef11" data</transaction>
</transactionList>

You ask git to merge the files together.  It sees two five-line files, 
with four lines in common, and one line different. It will probably 
insert both the lines, such as:

<transactionList count=3>
      <transaction>transaction "bd496a" data</transaction>
      <transaction>transaction "147f23" data</transaction>
      <transaction>transaction "00fade" data</transaction>
      <transaction>transaction "beef11" data</transaction>
</transactionList>

But notice, the "count" attribute now has the wrong value: it should be 
4, not 3.

Git's line-oriented text file handling has no way of detecting issues 
like this.


> ...I've done a few basic tests where I take a simple file and carry out that
> workflow, then reopen the merged file in Gnucash. So far, the result always
> seems to be as expected with all separately entered transactions present....
Good for you!  When it blows up, I would be interested in hearing how 
the problems manifested.
> So my question is whether anyone sees any potential issues with this.

TL; DR: I'm pretty sure it will fail, due to the XML structure becoming 
invalid.

As far as I can tell, you have a pretty standard situation of two people 
wanting to work on the same book file. There are FAQ's about this, see 
<https://wiki.gnucash.org/wiki/FAQ#Multiple_Computers.2C_Users.2C_...>. 
The way that has worked for me and others is to put the file in a shared 
location, but find some way to enforce that only one person edits the 
file at a time.


> Bonus question:
> Is there a particular algorithm for generating valid GUID's, or can they be
> any (unique) valid string with the allowed characters? I'm somewhat
> interested in the idea of programmatically adding elements to the xml file,
> and this would be a consideration in doing so.

That's easy. There is a specific format for GUIDs: they are 128-bit 
integers. The text representation you see uses 32 hexadecimal digits, 
0-9a-f, to display the 128-bit number. There is a convention that the 32 
digits are grouped into 8, 4, 4, 4, 12 digit groups, separated by 
hyphens. But the underlying data is a 128-bit number.

There are several algorithms. See 
<https://en.wikipedia.org/wiki/Universally_unique_identifier>. You 
probably can find a library in your favourite programming language for 
generating GUIDs according to many of those algorithms. From my limited 
experience of the GnuCash source code, I suspect they are generating 
version 4 GUIDs.

Good luck! Have fun.
     —Jim DeLaHunt