Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
bk smerge(7.3.3)	    BitKeeper User's Manual	      bk smerge(7.3.3)

NAME
       bk smerge - smart text-based 3-way file merge

SYNOPSIS
       bk smerge [-2efghn] [-An] [-an] -llocal -rremote	file

DESCRIPTION
       The bk smerge command compares the three	versions of the	file and iden-
       tifies all changes by either the	local or the  remote  version  of  the
       file  compared  to the greatest common ancestor (gca).  These groups of
       changes are known as conflict regions and are bounded by	a line that is
       identical in all	three versions at the beginning	of the conflict	region
       and at the end of the conflict region.  For each	region,	one or more of
       the  automerge algorithms (see below) are run to	see if the changes may
       be merged automatically.

       The bk smerge command does not  use  the	 traditional  diff3(1)	merge.
       There  are  a  number  of heuristics in the default enabled merge algo-
       rithms which help determine regions which are safe to automerge.	 These
       can simplify and	resolve	many conflict regions that can not be resolved
       in the traditional diff3(1) merge.  Please note,	smerge can only	be run
       on SCCS files.

       In  some	 scripts  users	 may  want to call smerge directly.  If	so, an
       example for usage is:

	   bk smerge -g	-l1.661	-r1.660.1.4 slib.c > slib.c.merged

       where 1.661 is the local	revision and 1.660.1.4 is the remote revision,
       slib.c  is  the	file name and slib.c.merged is the file	to which merge
       output is redirected.

       The string for the  local  or  remote  versions	of  the	 file  can  be
       expressed  in  the  form	 "rev+includes-excludes" where rev is a	normal
       revision	number like "1.661" and	includes and excludes are a comma sep-
       arated  list if revisions to include or exclude from the	base revision.
       (The include and/or exclude lists can be	omitted	if they	are empty.)

MERGE ALGORITHMS
       Each of the automerge algorithms	is described below.  Currently,	all of
       these  are  run by default, but that may	change in the future.  Any mix
       of these	may be selectively enabled or disabled.

       1. Merge	identical changes made by both sides
	   If both the local and the  remote  files  have  made	 an  identical
	   change  to  the GCA,	then this function will	resolve	the region and
	   replace it with the new text.
       2. Merge	when only one side changes
	   This	code finds conflict regions where only the local or the	remote
	   version  has	 made  any  changes.   In  this	 case  the conflict is
	   resolved and	the side that made changes is kept.  This is the  tra-
	   ditional diff3(1) type automerge algorithm.
       3. Merge	adjacent, non-overlapping modifications	on both	sides
	   This	 code attempts to find a conflict consisting of	a text substi-
	   tution in both the local and	remote versions	of the file.   A  sub-
	   stitution  is  a  line  or  group of	lines that is deleted and then
	   replaced with zero or more lines.  If there is  a  conflict	region
	   that	 contains lines	substituted in the local file that are unmodi-
	   fied	in the remote and there	are lines substituted  in  the	remote
	   file	that are unmodified in the local file, then a merge of the two
	   substitutions is performed.

	   Here	is an example of a conflict region (in the -g  output  format)
	   where this algorithm	will successfully resolve the conflict.

	       <<<<<<< local slib.c 1.642.1.6 vs 1.645
		    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
	       -    assert(sc->tree);
	       -    sccs_sdelta(sc, sc->tree, file);
	       +    assert(HASGRAPH(sc));
	       +    sccs_sdelta(sc, sccs_ino(sc), file);
	       <<<<<<< remote slib.c 1.642.1.6 vs 1.642.2.1
	       -    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
	       +    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
		    assert(sc->tree);
		    sccs_sdelta(sc, sc->tree, file);
	       >>>>>>>

	   The block after the resolve will be:

		    sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
		    assert(HASGRAPH(sc));
		    sccs_sdelta(sc, sccs_ino(sc), file);

	   Multiple substitutions are not yet handled.
       4. Merge	identical changes at the start of a conflict
	   This	 code  recognizes one or more lines at the beginning the local
	   and remote versions of a conflict region that  are  identical.   If
	   there  is  a	 block	of lines that are identical then the region is
	   split into two regions with the identical  lines  in	 a  region  by
	   themselves.	This block will	later be resolved by algorithm #1.
       5. Merge	identical changes at the end of	a conflict
	   This	 is  similar  to  algorithm  #4, except	it looks for identical
	   lines on both sides at the end of the conflict region.
       6. Merge	identical deletions made by both sides
	   If both the local and remote	version	of a region have  deleted  the
	   same	 non-zero  block of lines at the end of	the region, then split
	   the region into two with the	deletions in a separate	 region.   The
	   deletions will then get autoresolved.

       When  a conflict	regions	is identified, then the	enabled	algorithms are
       run on the block	repeatedly until the block is resolved or  no  further
       progress	is made.

       Default conflict	output format is as follows:

	   <<<<<<< gca slib.c 1.642.1.6
		sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
		assert(sc->tree);
		sccs_sdelta(sc,	sc->tree, file);
	   <<<<<<< local slib.c	1.645
		sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
		assert(HASGRAPH(sc));
		sccs_sdelta(sc,	sccs_ino(sc), file);
	   <<<<<<< remote slib.c 1.642.2.1
		sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
		assert(sc->tree);
		sccs_sdelta(sc,	sc->tree, file);
	   >>>>>>>

       Lines  with  "<<<<<<<" indicate the file	the conflict region is from in
       the form: <<<<<<< label file revision followed by  the  conflict	 lines
       from  that  file.   The	end  of	 the  conflict	region is indicated by
       ">>>>>>>".  Examples of conflict	output can be viewed by	using  the  -e
       option.

OPTIONS
       -2   Enable the 2 way output format (like diff3(1)).
       -g   Enable  'gca'  output format that shows the	local and remote files
	    like a unified diff	between	the GCA	and that file.	 This  is  the
	    recommended	output format, but not the default because it confuses
	    people the first time they see it.
       -n   Enable the 'newonly' output	format.	  (like	 -2  except  it	 marks
	    added lines).
       -e   Print examples of all 4 output formats from	bk smerge.
       -an  Enable  merge  functions  n,  where	n is a comma separated list of
	    automerge algorithms specified by number.  -aall will  enable  all
	    automerge  algorithms.   Use  bk  smerge -h	to find	the algorithms
	    enabled by default.
       -An  Disable merge functions n, where n is a comma  separated  list  of
	    automerge algorithms specified by number.  -Aall will turn off all
	    automerging.
       -f   Enable fdiff output.  (Used	internally by bk fm3tool)
       -h   Display  automerge	algorithms  by	number	that  are  enabled  by
	    default.   If  used	in conjunction with -a or -A, asterisks	denote
	    enabled algorithms.

EXIT STATUS
       bk smerge returns exit status:

       0   if there were no conflicts
       1   if there were conflicts
       2   if an error occurred

SEE ALSO
       diff3(1), bk-resolve, bk-resolving, bk-merge

CATEGORY
       Utility

BitKeeper Inc			      1E1		      bk smerge(7.3.3)

NAME | SYNOPSIS | DESCRIPTION | MERGE ALGORITHMS | OPTIONS | EXIT STATUS | SEE ALSO | CATEGORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=smerge&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help