Differences between revisions 9 and 10
Revision 9 as of 2013-01-18 00:10:55
Size: 4492
Editor: JulianFoad
Comment:
Revision 10 as of 2013-01-18 16:19:49
Size: 5231
Editor: JulianFoad
Comment:
Deletions are marked like this. Additions are marked like this.
Line 34: Line 34:
||<tablewidth="90%">svn:special ||yes [2] ||no ||no ||no ||no ||
||svn:mime-type ||n/a ||bin ||txt ||txt ||txt ||
||<tablewidth="90%">svn:special ||yes ||no ||no ||no ||no ||
||svn:mime-type ||n/a  [1] ||bin ||txt ||txt ||txt ||
Line 38: Line 38:
||On-disk attributes? ||none [1] ||ro, x ||ro, x ||ro, x ||ro, x || ||On-disk attributes? ||none [2] ||ro, x ||ro, x ||ro, x ||ro, x ||
Line 43: Line 43:
To prepare for a merge, in principle the 'mine' text is translated as follows, to end up in RNF for comparison with the incoming 'left' and 'right' texts. To prepare for a merge:
Line 45: Line 45:
 1. translate to RNF according to the old 'mine' props
 1. translate to WCF according to the new merged props*
 1. translate to RNF according to the new merged props*
 * the 'mine' text is translated so as to end up in RNF for comparison with the incoming 'left' and 'right' texts
Line 49: Line 47:
*If the merged properties have conflicts, then ###?  * the 'left' text is translated to the (kw? eol?) form of the 'right' text ### ... [3?]

==== Translating 'mine' ====
The 'mine' text is translated as follows (in principle), to end up in RNF for comparison with the incoming 'left' and 'right' texts:

 1. translate to RNF, according to the old 'mine' props
 1. translate to WCF and back to RNF, according to the new merged props [4]
Line 53: Line 57:
Steps 2 and 3 ensure that any keywords (### and eol-style?) that should be enabled after the merge, are ###? Step 2 ensures that the file is normalized with respect to the eol-style (and, in theory, any keywords [5]) that will be in use after the merge. This prevents the merge from thinking that every line has changed, which is helpful in cases such as when the text already had the new-style line endings and the purpose of the merge is just to add the property.
Line 55: Line 59:
Also the 'left' text is translated to the (kw? eol?) form of the 'right' text ### ... ==== Notes ====
Note [1]: The WC merge code currently has 'binary' overriding 'special' if both old and new props indicate 'binary': see detranslate_wc_file(). Looks like a bug, as 'special' takes precedence over all other translations in other cases.
Line 57: Line 62:
 . ### Bert says: Merge uses a different kind of repository normal form than our pristine store... Merge always normalizes EOL to '\n' for any svn:eol-style, while our pristine handling only does that for 'native' and '\n' itself. Note [2]: A symlink doesn't have any on-disk attributes of its own on typical Unix-style filesystems so I imagine Subversion shouldn't be trying to change them. However, when checked out on a system that doesn't support symlinks, it becomes a normal file, and maybe then we apply the attributes.
Line 59: Line 64:
Note [1]: A symlink doesn't have any on-disk attributes of its own on typical Unix-style filesystems so I imagine Subversion shouldn't be trying to change them. However, when checked out on a system that doesn't support symlinks, it becomes a normal file, and maybe then we apply the attributes. Note [3]: (Bert says:) Merge uses a different kind of repository normal form than our pristine store... Merge always normalizes EOL to '\n' for any svn:eol-style, while our pristine handling only does that for 'native' and '\n' itself.
Line 61: Line 66:
Note [2]: The WC merge code has 'binary' overriding 'special': see detranslate_wc_file(). Don't know if everywhere does the same. Note [4]: If the merged properties have conflicts, then ###?

Note [5]: In practice we don't currently detranslate (normalize) any keywords that are present in the 'mine' text but not enabled, and that become enabled by the new value of svn:keyword property. See detranslate_wc_file().

How Subversion Merges a File

This page is an attempt to formalize how Subversion merges changes to a single file. It aims to cover all the user-visible aspects, including details such as:

  • 'binary' file
  • keyword expansion
  • eol-style
  • no-op change
  • UI notification
  • the merge during an update

File Merge - General Definition

  • Three node-versions are involved: 'left', 'right', 'mine'.
  • All node-versions "live at" the same WC path.
  • Node kind is 'file' for all node-versions involved.
  • The file has 'props' and 'text'; both are merged.
  • Props are merged independently, but text merge depends on the props.

A 3-way diff style of merge is used, for both props and text. (That is, the fact that 'left' might not be the youngest common ancestor is not taken into account: the "4-way diff" aka "variance-adjusted patching" technique is not used.)

Properties and Text

Props are merged independently of the text, whereas the text merge can be affected by some of the properties, notably svn:keywords and svn:eol-style. The on-disk 'executable' and 'read-only' attributes also may be altered, depending on the properties and on whether a lock is known to be held on this node's repository path.

Properties Merge

For each property name 'P', a merge is performed on the three values (of property 'P' from each of the three node-versions), independently of any other property name. Where one or two of the three node-versions do not have the property named 'P', the value is regarded as 'null'.

  • ### A property value is merged as a 3-way text merge, or as a simple choice of one of the values?

svn:mergeinfo is merged semantically. ### All other properties are merged without semantic interpretation of the values?

If the values conflict, a 'property conflict' is recorded for the property name 'P'. Property conflicts may be recorded for none, any or all of the property names involved in the merge. ### See 'Conflicts'.

Text Translation

The following table show what translations are performed between "repository normal form" (RNF) and "working copy form" (WCF):

svn:special

yes

no

no

no

no

svn:mime-type

n/a [1]

bin

txt

txt

txt

svn:eol-style

n/a

n/a

no

'native'

'CR', 'CRLF', 'LF' ###?

What's translated?

symlink

kw

kw

kw, eol

kw (and eol is repaired if another type is encountered)

On-disk attributes?

none [2]

ro, x

ro, x

ro, x

ro, x

To prepare for a merge:

  • the 'mine' text is translated so as to end up in RNF for comparison with the incoming 'left' and 'right' texts
  • the 'left' text is translated to the (kw? eol?) form of the 'right' text ### ... [3?]

Translating 'mine'

The 'mine' text is translated as follows (in principle), to end up in RNF for comparison with the incoming 'left' and 'right' texts:

  1. translate to RNF, according to the old 'mine' props
  2. translate to WCF and back to RNF, according to the new merged props [4]

Step 1 simply returns the text to its own RNF.

Step 2 ensures that the file is normalized with respect to the eol-style (and, in theory, any keywords [5]) that will be in use after the merge. This prevents the merge from thinking that every line has changed, which is helpful in cases such as when the text already had the new-style line endings and the purpose of the merge is just to add the property.

Notes

Note [1]: The WC merge code currently has 'binary' overriding 'special' if both old and new props indicate 'binary': see detranslate_wc_file(). Looks like a bug, as 'special' takes precedence over all other translations in other cases.

Note [2]: A symlink doesn't have any on-disk attributes of its own on typical Unix-style filesystems so I imagine Subversion shouldn't be trying to change them. However, when checked out on a system that doesn't support symlinks, it becomes a normal file, and maybe then we apply the attributes.

Note [3]: (Bert says:) Merge uses a different kind of repository normal form than our pristine store... Merge always normalizes EOL to '\n' for any svn:eol-style, while our pristine handling only does that for 'native' and '\n' itself.

Note [4]: If the merged properties have conflicts, then ###?

Note [5]: In practice we don't currently detranslate (normalize) any keywords that are present in the 'mine' text but not enabled, and that become enabled by the new value of svn:keyword property. See detranslate_wc_file().

Text Merge

  • ### ...

Executable and Read-Only Attributes

  • ### (The on-disk 'executable' and 'read-only' attributes also may be altered, depending on the properties and on whether a lock is known to be held on this node's repository path.)

External Merge Tool

An external 3-way text merge tool may be configured. It is used instead of the internal text merge. It is only used when a text merge is deemed appropriate, and not when the file content is deemed 'binary', nor for a trivial merge.

  • ### Explain the difference between 'diff3-cmd' and 'merge-cmd' configs. ### Explain the 'diff3-has-program-arg' config.

FileMerge (last edited 2013-01-18 16:19:49 by JulianFoad)