synch_hg_p4/synch_hg_xxx.pl
changeset 0 02cd6b52f378
child 1 4a4ca5a019bb
equal deleted inserted replaced
-1:000000000000 0:02cd6b52f378
       
     1 #! perl
       
     2 
       
     3 # sync_hg_xxx.pl
       
     4 
       
     5 use strict;
       
     6 use Getopt::Long;
       
     7 use File::Temp qw/ tempfile tempdir /;	# for tempfile()
       
     8 
       
     9 my $verbose;
       
    10 my $debug = 0;
       
    11 my $rootdir;
       
    12 my $help;
       
    13 my $remoterepo;
       
    14 my $hgbranch;
       
    15 my $sync_prefix = "sync_";
       
    16 
       
    17 # abandon_sync, all ye who enter here
       
    18 # This should send a notification to someone, as it will probably mean manual repair
       
    19 #
       
    20 sub abandon_sync(@)
       
    21 	{
       
    22 	print "ERROR - synchronisation of $rootdir abandoned\n\n";
       
    23 	print @_;
       
    24 	print "\n\n";
       
    25 	exit(1);
       
    26 	}
       
    27 	
       
    28 # utility to run an external command
       
    29 #
       
    30 sub run_cmd($;$)
       
    31 	{
       
    32 	my ($cmd,$failurematch) = @_;
       
    33 	print "--- $cmd\n" if ($verbose || $debug);
       
    34 	my @output = `$cmd`;
       
    35 	print @output,"\n---\n" if ($debug);
       
    36 	
       
    37 	if (defined $failurematch)
       
    38 		{
       
    39 		if (grep /$failurematch/, @output)
       
    40 			{
       
    41 			abandon_sync("COMMAND FAILED: $cmd\n", @output,"\n\n",
       
    42 				"Output matched $failurematch\n");
       
    43 			}
       
    44 		else
       
    45 			{
       
    46 			print "CMD OK - Didn't match /$failurematch/\n" if ($debug);
       
    47 			}
       
    48 		}
       
    49 	if ($?)
       
    50 		{
       
    51 		print @output,"\n---\n" if ($verbose);
       
    52 		abandon_sync("COMMAND FAILED: exit status = $?\n",$cmd,"\n");
       
    53 		}
       
    54 	
       
    55 	return @output;
       
    56 	}
       
    57 	
       
    58 
       
    59 # -------------- hg section -------------
       
    60 #
       
    61 # Code relating to other SCM system is abstracted into 
       
    62 # functions to do relatively simple actions. This section
       
    63 # contains the driving logic for the script, and all of the
       
    64 # manipulations of Mercurial
       
    65 #
       
    66 
       
    67 sub scm_usage();		# forward declarations
       
    68 sub scm_options();
       
    69 sub scm_init($@);
       
    70 sub scm_checkout($);	# non-destructive, i.e. leave untouched any workspace files not managed in SCM
       
    71 sub scm_checkin($$$$$$);
       
    72 
       
    73 sub Usage(;$)
       
    74 	{
       
    75 	my ($errmsg) = @_;
       
    76 	print "\nERROR: $errmsg\n" if (defined $errmsg);
       
    77 	scm_usage();
       
    78 	print <<'EOF';
       
    79 
       
    80 General options:
       
    81 
       
    82 -root rootdir       root of the Mercurial gateway repository
       
    83 -v                  verbose
       
    84 -h                  print this usage information
       
    85 
       
    86 Setting up a new synchronisation:
       
    87 
       
    88 -clone remoterepo   clones gateway from remote repository 
       
    89 -branch hgbranch    Mercurial branch name (if needed)
       
    90 
       
    91 EOF
       
    92 	exit 1;
       
    93 	}
       
    94 
       
    95 Usage() if !GetOptions(
       
    96 	'root=s' => \$rootdir,
       
    97 	'h' => \$help,
       
    98 	'v' => \$verbose,
       
    99 	'debug' => \$debug,
       
   100 	'clone=s' => \$remoterepo,
       
   101 	'branch=s' => \$hgbranch,
       
   102 	scm_options()
       
   103 	);
       
   104 
       
   105 Usage() if ($help);
       
   106 
       
   107 Usage("Must specify root directory for Mercurial gateway") if (!defined $rootdir);
       
   108 Usage("-branch is only used with -clone") if (defined $hgbranch && !defined $remoterepo);
       
   109 
       
   110 if ($verbose)
       
   111 	{
       
   112 	my @hgversion = run_cmd("hg --version");
       
   113 	print @hgversion;
       
   114 	}
       
   115 
       
   116 # utility to return the heads descended from a particular point
       
   117 #
       
   118 sub hg_heads($)
       
   119 	{
       
   120 	my ($rev_on_branch) = @_;
       
   121 	my @heads = run_cmd("hg heads --template {rev}\\t{tags}\\n $rev_on_branch");
       
   122 	return @heads;
       
   123 	}
       
   124 
       
   125 # return an unsorted list of synchronisation points, identified by
       
   126 # tags beginning with "sync_"
       
   127 # 
       
   128 sub hg_syncpoints(;$)
       
   129 	{
       
   130 	my ($tip_rev) = @_;
       
   131 	my @tags = run_cmd("hg tags");
       
   132 	my @syncpoints;
       
   133 	foreach my $tag (@tags)
       
   134 		{
       
   135 		if ($tag =~ /^tip\s+(\d+):\S+$/)
       
   136 			{
       
   137 			$$tip_rev = $1 if (defined $tip_rev);
       
   138 			next;
       
   139 			}
       
   140 		if ($tag =~ /^$sync_prefix(.*\S)\s+\S+$/)
       
   141 			{
       
   142 			push @syncpoints, $1;
       
   143 			next
       
   144 			}
       
   145 		}
       
   146 	if ($debug)
       
   147 		{
       
   148 		printf "Found %d syncpoints in %d tags:", scalar @syncpoints, scalar @tags;
       
   149 		print join("\n * ", "",@syncpoints), "\n";
       
   150 		}
       
   151 	return @syncpoints;
       
   152 	}
       
   153 
       
   154 my $hg_updated = 0;
       
   155 
       
   156 # Update the Mercurial workspace to a given sync point
       
   157 #
       
   158 sub hg_checkout($)
       
   159 	{
       
   160 	my ($scmref) = @_;
       
   161 	
       
   162 	my $tag = $sync_prefix.$scmref;
       
   163 	my @output = run_cmd("hg update --clean --rev $tag", "^abort:");
       
   164 	$hg_updated = 1;	# could check the output in case it didn't change anything
       
   165 	}
       
   166 
       
   167 # 0. Create the gateway repository, if -clone is specified
       
   168 
       
   169 if (defined $remoterepo)
       
   170 	{
       
   171 	Usage("Cannot create gateway because $rootdir already exists") if (-d $rootdir);
       
   172 
       
   173 	my $clonecmd = "clone";
       
   174 	$clonecmd .= " --rev $hgbranch" if (defined $hgbranch);
       
   175 	my @output = run_cmd("hg $clonecmd $remoterepo $rootdir");
       
   176 	$hg_updated = 1;
       
   177 	}
       
   178 
       
   179 chdir $rootdir;
       
   180 Usage("$rootdir is not a Mercurial repository") if (!-d ".hg");
       
   181 
       
   182 my $something_to_push = 0;
       
   183 
       
   184 # 1. Prime the SCM system, and get the ordered list of changes available to 
       
   185 # convert into Mercurial commits
       
   186 
       
   187 my $first_sync;		# is this the first synchronisation?
       
   188 my $scm_tip_only;	# can we process a series of changes in the SCM system?
       
   189 
       
   190 my $tip_rev = -1;
       
   191 my @syncpoints = hg_syncpoints(\$tip_rev);
       
   192 
       
   193 if (scalar @syncpoints != 0)
       
   194 	{
       
   195 	$first_sync = 0;	# no - it's already synchronised
       
   196 	$scm_tip_only = 0;	# so can allow sequence of SCM changes
       
   197 	}
       
   198 else
       
   199 	{
       
   200 	print "First synchronisation through this gateway\n" if ($verbose);
       
   201  	$first_sync = 1;
       
   202 	if ($tip_rev != -1)
       
   203 		{
       
   204  		$scm_tip_only = 1;	# because there's already something in the repository
       
   205  		}
       
   206  	else
       
   207  		{
       
   208 		print "Mercurial repository is empty\n" if ($verbose);
       
   209 		$scm_tip_only = 0;	# allow multiple SCM changes, because there's nothing to merge with
       
   210 		}
       
   211 	}
       
   212 
       
   213 my $opening_scmtag;	# ancestor by which we judge the headcount of the result
       
   214 my $latest_scmtag;
       
   215 
       
   216 my @scmrefs = scm_init($scm_tip_only, @syncpoints);
       
   217 
       
   218 if (scalar @scmrefs == 0)
       
   219 	{
       
   220 	print "No changes to process in local SCM\n";
       
   221 	$opening_scmtag = $tip_rev;
       
   222 	}
       
   223 else
       
   224 	{
       
   225 	$opening_scmtag = $sync_prefix.$scmrefs[0];
       
   226 	}
       
   227 $latest_scmtag = $opening_scmtag;
       
   228 
       
   229 if ($scm_tip_only && scalar @scmrefs > 1)
       
   230 	{
       
   231 	print "ERROR - cannot handle multiple SCM changes in this situation\n";
       
   232 	exit(1);
       
   233 	}
       
   234 
       
   235 # 2. Process the SCM changes, turning them into Mercurial commits and marking with tags
       
   236 # - we guarantee that there is at most one change, if this is the first synchronisation
       
   237 
       
   238 foreach my $scmref (@scmrefs)
       
   239 	{
       
   240 	my ($user,$date,@description) = scm_checkout($scmref);
       
   241 	
       
   242 	# commit the result
       
   243 
       
   244 	my ($fh,$filename) = tempfile();
       
   245 	print $fh join("\n",@description), "\n";
       
   246 	close $fh;
       
   247 	
       
   248 	run_cmd("hg commit --addremove --date \"$date\" --user \"$user\" --logfile  $filename", "^abort\:");
       
   249 	$something_to_push = 1;
       
   250 	
       
   251 	unlink($filename);	# remove temporary file
       
   252 
       
   253 	my $tag = $sync_prefix.$scmref;
       
   254 	run_cmd("hg tag --local $tag");
       
   255 	$latest_scmtag = $tag;
       
   256 	print "Synchronised $scmref into Mercurial gateway repository\n";
       
   257 	}
       
   258 
       
   259 # 3. Put the full Mercurial state into the SCM, if this is the first synchronisation
       
   260 
       
   261 if ($first_sync)
       
   262 	{
       
   263 	my @traceback = run_cmd("hg log --limit 1 --template {rev}\\t{node}\\t{tags}\\n");
       
   264 	my $line = shift @traceback;
       
   265 
       
   266 	chomp $line;
       
   267 	my ($rev,$node,$tags) = split /\t/,$line;
       
   268 	
       
   269 	if ($rev != 0)
       
   270 		{
       
   271 		# repository was not empty, so need to commit the current state back into Perforce
       
   272 	
       
   273 		my @description = run_cmd("hg log --rev $rev --template \"{author}\\n{date|isodate}\\n{desc}\"");
       
   274 		chomp @description;
       
   275 		my $author = shift @description;
       
   276 		my $date = shift @description;
       
   277 		my @changes = run_cmd("hg status --clean");	# include info on unmodified files
       
   278 		@changes = sort @changes;
       
   279 
       
   280 		# Deliver changes to SCM
       
   281 		my $scmref = scm_checkin($node,$author,$date,\@changes,\@description,$tags);
       
   282 		
       
   283 		my $tag = $sync_prefix.$scmref;
       
   284 		run_cmd("hg tag --local $tag");
       
   285 		$latest_scmtag = $tag;
       
   286 		print "Synchronised $scmref from Mercurial gateway, to initialise the synchronisation\n";
       
   287 		}
       
   288 	
       
   289 	$opening_scmtag = $latest_scmtag;	# don't consider history before this point
       
   290 	}
       
   291 
       
   292 
       
   293 # 3. pull from Mercurial default path, deal with new stuff
       
   294 
       
   295 my @pull_output = run_cmd("hg pull --update");
       
   296 $hg_updated = 1;
       
   297 
       
   298 my @heads = hg_heads($opening_scmtag);
       
   299 
       
   300 if (scalar @heads > 1)
       
   301 	{
       
   302 	# more than one head - try a safe merge
       
   303 	print "WARNING: multiple heads\n",@heads,"\nMerge is needed\n\n\n" if ($verbose);
       
   304 	
       
   305 	my @merge_output = run_cmd("hg --config \"ui.merge=internal:fail\" merge");	# which head?
       
   306 	if ($merge_output[0] =~ / 0 files unresolved/)
       
   307 		{
       
   308 		# successful merge - commit it.
       
   309 		run_cmd("hg commit --message \"Automatic merge\"");
       
   310 		$something_to_push = 1;
       
   311 		}
       
   312 	else
       
   313 		{
       
   314 		# clean up any partially merged files
       
   315 		run_cmd("hg update -C");
       
   316 		}
       
   317 	}
       
   318 
       
   319 # 4. Identify the sequence of Mercurial changes on the trunk and put them into the SCM
       
   320 # - Do only the head revision if this is the first synchronisation, to avoid copying ancient history
       
   321 
       
   322 my $options = "--follow-first";
       
   323 $options .= " --prune $latest_scmtag";
       
   324 
       
   325 my @traceback = run_cmd("hg log $options --template {rev}\\t{node}\\t{tags}\\n");
       
   326 foreach my $line (reverse @traceback)
       
   327 	{
       
   328 	chomp $line;
       
   329 	my ($rev,$node,$tags) = split /\t/,$line;
       
   330 	if ($tags =~ /$sync_prefix/)
       
   331 		{
       
   332 		# shouldn't happen - it would mean that tip goes back to an ancestor
       
   333 		# of the latest sync point
       
   334 		abandon_sync("Cannot handle this structure\n",@traceback);
       
   335 		}
       
   336 	
       
   337 	# Read commit information and update workspace from Mercurial
       
   338 	
       
   339 	my @description = run_cmd("hg log --rev $rev --template \"{author}\\n{date|isodate}\\n{desc}\"");
       
   340 	chomp @description;
       
   341 	my $author = shift @description;
       
   342 	my $date = shift @description;
       
   343 	my @changes = run_cmd("hg status --rev $latest_scmtag --rev $rev");
       
   344 	@changes = sort @changes;
       
   345 
       
   346 	run_cmd("hg update -C --rev $rev");
       
   347 	$hg_updated = 1;
       
   348 	
       
   349 	# Deliver changes to SCM
       
   350 	my $scmref = scm_checkin($node,$author,$date,\@changes,\@description,$tags);
       
   351 	
       
   352 	# Tag as the latest sync point
       
   353 	my $tag = $sync_prefix.$scmref;
       
   354 	run_cmd("hg tag --local $tag");
       
   355 	$latest_scmtag = $tag;
       
   356 	print "Synchronised $scmref from Mercurial gateway\n";
       
   357 	}
       
   358 
       
   359 # 3. push changes to the destination gateway
       
   360 
       
   361 if ($something_to_push)
       
   362 	{
       
   363 	my @output = run_cmd("hg -v push --force --rev $latest_scmtag");
       
   364 	print "\n",@output,"\n" if ($verbose);
       
   365 	print "Destination Mercurial repository has been updated\n"; 
       
   366 	}
       
   367 else
       
   368 	{
       
   369 	print "Nothing to push to destination Mercurial repository\n";
       
   370 	}
       
   371 
       
   372 # 4. Check to see if we are in a clean state
       
   373 
       
   374 @heads = hg_heads($opening_scmtag);
       
   375 if (scalar @heads > 1)
       
   376 	{
       
   377 	print "\n------------------\n";
       
   378 	print "WARNING: Mercurial repository has multiple heads - manual merge recommended\n";
       
   379 	}
       
   380 
       
   381 exit(0);
       
   382 
       
   383 
       
   384 # -------------- SCM section -------------
       
   385 #
       
   386 # Code relating to non-Mercurial SCM system.
       
   387 # This version implements the sync with XXX
       
   388 #
       
   389 
       
   390 # Utility functions you might want to call are:
       
   391 #
       
   392 # run_cmd($cmd)
       
   393 # - Function which runs the specified command in a subshell and returns the stdout output as a list
       
   394 #   of strings. The whole script will terminate if the command returns with a non-zero exit status.
       
   395 #
       
   396 # abandon_sync(@messagelines)
       
   397 # - Terminate the synchronisation script and pass on the message to someone who might care...
       
   398 #
       
   399 # $hg_updated
       
   400 # - Global variable set to 1 if Mercurial changes the content of the workspace. This can be used to
       
   401 #   optimise the XXX system processing during initialisation, because it indicates when the workspace
       
   402 #   can be considered "clean" by the XXX system. Should be set to 0 whenever the XXX system knows the
       
   403 #   state of the workspace.
       
   404 #
       
   405 # hg_checkout($scmref)
       
   406 # - Function to call "hg update" to the sync label associated with $scmref. Used during the scm_init
       
   407 #   function as part of getting the workspaces in harmony before transferring changes. Will set
       
   408 #   $hg_updated to 1.
       
   409 
       
   410 
       
   411 # scm_usage()
       
   412 #
       
   413 # This function is called to supply the main "usage" statement for the script, as the
       
   414 # interesting description is all about the interaction between Mercurial and XXX. It takes no
       
   415 # arguments and should return nothing.
       
   416 #
       
   417 sub scm_usage()
       
   418 	{
       
   419 	print <<'EOF';
       
   420 
       
   421 perl sync_hg_xxx.pl -root rootdir [options]
       
   422 version 0.7
       
   423  
       
   424 Synchronise a branch in XXX with a branch in Mercurial.
       
   425 
       
   426 The branch starts at rootdir, which is a local Mercurial repository.
       
   427 The Perforce clientspec is assumed to exist, to specify modtime & rmdir, 
       
   428 and to exclude the .hg directory from the rootdir.
       
   429 
       
   430 The tool will sync rootdir/... to the specified changelist, and
       
   431 then reflect all changes affecting this part of the directory tree into
       
   432 Mercurial.
       
   433 
       
   434 The -first option is used to specify the first sync point if the gateway
       
   435 has not been previously synchronised, e.g. when -clone is specified.
       
   436 
       
   437 Perforce-related options:
       
   438 
       
   439 -m maxchangelist    highest changelist to consider
       
   440                     defaults to #head
       
   441 
       
   442 EOF
       
   443 	}
       
   444 
       
   445 my $max_changelist;			# put XXX-specific global variables here
       
   446 
       
   447 sub scm_options()
       
   448 	{
       
   449 	# set defaults
       
   450 	
       
   451 	$max_changelist = "#head";		# initialise the XXX global variables here, otherwise it doesn't happen
       
   452 	
       
   453 	# return the GetOpt specification
       
   454 	return (
       
   455 		'm|max=s' => \$max_changelist,		# add your own bits of GetOpt arguments
       
   456 		);
       
   457 	}
       
   458 
       
   459 
       
   460 # scm_init ($tip_only, @syncpoints)
       
   461 #
       
   462 # The main code calls this routine once, passing two arguments, and expects to get a 
       
   463 # list of identifiers to XXX changes which could be synchronised as individual Mercurial
       
   464 # commits. These references can be anything which can be used as part of a Mercurial tag name,
       
   465 # and the main code will call back into this routine supplying the references one at a time
       
   466 # in the list order.
       
   467 #
       
   468 # If $tip_only is true, then the synchronisation can only handle the most recent version
       
   469 # of the code in the XXX system, and will not be able to sync intermediate steps. This usually
       
   470 # means that this is the first synchronisation of this branch with Mercurial. At most one identifier
       
   471 # should be returned.
       
   472 #
       
   473 # @syncpoints contains a list of identifiers extracted from the local sync_* tags which mark a change
       
   474 # that was synchronised with Mercurial in some previous run. This information allows the XXX system
       
   475 # to ignore changes which have previously been processed, and to set itself into a state where
       
   476 # the workspace corresponds to the contents of the XXX system at that point.
       
   477 #
       
   478 # The function returns the list of change identifiers for changes to be taken out of XXX and applied
       
   479 # to Mercurial. This list can be empty if there are no new changes since the last synchronisation point,
       
   480 # or if there is no content in the branch.
       
   481 
       
   482 sub scm_init($@)
       
   483 	{
       
   484 	my ($tip_only, @syncpoints) = @_;
       
   485 	
       
   486 	my $first_changelist;
       
   487 	
       
   488 	if ($tip_only)
       
   489 		{
       
   490 		# Script says we must synchronise from the XXX tip revision
       
   491 		
       
   492 		# Find the first changelist
       
   493 
       
   494 		if (!defined $first_changelist)
       
   495 			{
       
   496 			print "XXX branch contains no changes\n";
       
   497 			return ();
       
   498 			}
       
   499 		print "Synchronisation from tip ($first_changelist)\n" if ($verbose);
       
   500 		# fall through to complete the initialisation
       
   501 		}
       
   502 	else
       
   503 		{
       
   504 		# deduce the last synchronisation point from the @syncpoints list
       
   505 
       
   506 		$first_changelist = some_function_of(@syncpoints);
       
   507 		
       
   508 		# Get Mercurial & XXX into the synchronised state
       
   509 
       
   510 		hg_checkout($first_changelist);		# call back to Mercurial to update from hg repository
       
   511 		
       
   512 		# get XXX into state associated with $first_changelist
       
   513 
       
   514 		## NB this is a bit Perforce specific - you might prefer to separate tip_only processing
       
   515 		## from the normal "changes since last synchronisation" processing
       
   516 		##
       
   517 		$first_changelist += 1;		# we've already synched that one
       
   518 		##
       
   519 		}
       
   520 	
       
   521 	# enumerate the changelists available from the XXX system & return as an ordered list
       
   522 
       
   523 	my @scmrefs = some_function($first_changelist);
       
   524 
       
   525 	if ($verbose)
       
   526 		{
       
   527 		printf "Found %d new changelists to process\n", scalar @scmrefs;
       
   528 		print join(", ", @scmrefs), "\n";
       
   529 		}
       
   530 	
       
   531 	return @scmrefs;
       
   532 	}
       
   533 
       
   534 # scm_checkout($scmref)
       
   535 #
       
   536 # Update the workspace to reflect the given SCM reference
       
   537 #
       
   538 # This update should not change files which are not currently managed by the XXX system, but
       
   539 # should delete workspace files if the XX change involved deleting files. It is useful, but not essential,
       
   540 # for empty directories to be removed if they become empty due to deletions recorded in the XXX change.
       
   541 #
       
   542 # The function returns a list containing three things:
       
   543 # 
       
   544 # $change_user - the username to be recorded for the Mercurial commit
       
   545 # $change_date - the date to be recorded for the Mercurial commit (yyyy-mm-dd hh:mm:ss format)
       
   546 # @change_description - the commit message to be used in Mercurial, as a list of lines of text
       
   547 #
       
   548 # The lines in the change description should not contain end of line markers, as these will be supplied
       
   549 # by the main code.
       
   550 #
       
   551 sub scm_checkout($)
       
   552 	{
       
   553 	my ($scmref) = @_;
       
   554 	
       
   555 	my @change_description;
       
   556 	my $change_date;
       
   557 	my $change_user;
       
   558 	
       
   559 	# obtain the user , date and description for the given change identifier
       
   560 	
       
   561 	# apply the change to the workspace, ready for Mercurial to deduce with "hg commit --addremove"
       
   562 	
       
   563 	return ($change_user,$change_date,@change_description);
       
   564 	}
       
   565 
       
   566 
       
   567 # scm_checkin($hgnode,$author,$date,$changes,$description,$tags)
       
   568 #
       
   569 # Describe the changes to the workspace as an SCM change, and return the new identifier (for use in a tag)
       
   570 #
       
   571 # The function receives 6 parameters, all of which are associated with the Mercurial commit
       
   572 #
       
   573 # $hgnode      - Mercurial commit reference, as a globally unique hexadecimal identifier
       
   574 # $author      - the author recorded in the commit
       
   575 # $date        - the date recorded in the commit, in ISO date format (yyyy-mm-dd hh:mm:ss)
       
   576 # $changes     - Perl reference to the list of file changes (more information below)
       
   577 # $description - Perl reference to the list of lines in the commit message
       
   578 # $tags        - Perl reference to the list of (non-local) tags associated with this commit
       
   579 #
       
   580 # The changes come from the Mercurial "hg status" command, and consist of a filename relative to the
       
   581 # root of the repository, prefixed by a single letter code and a space. The codes that this routine
       
   582 # must handle are M = modify, R = remove, A = add, and C = clean. The C codes are only used for the
       
   583 # first synchronisation, and so should be handled as "add if not already in XXX". All of the implied 
       
   584 # changes have already been applied to the files in the workspace - the R files have been deleted, 
       
   585 # the A files have been added and the M files contain the desired content.
       
   586 #
       
   587 # The $hgnode should be recorded in the description in the XXX system, as should the $author and $date if
       
   588 # they can't be used directly. 
       
   589 #
       
   590 # The function returns the identifier for the completed change, which will be tagged in the Mercurial
       
   591 # repository and reported to scm_init() in future synchronisation runs.
       
   592 #
       
   593 # WARNING: The tag information isn't currently filtered properly, and it is likely that there will
       
   594 # need to be a separate scm_tag() function to handle the important Mercurial tags explicitly. Don't try
       
   595 # to do much with the tag information just yet.
       
   596 #
       
   597 sub scm_checkin($$$$$$)
       
   598 	{
       
   599 	my ($hgnode,$author,$date,$changes,$description,$tags) = @_;
       
   600 	
       
   601 	my @hg_tags = grep !/^tip$/, split /\s+/, $tags;
       
   602 	my @xxx_modify;
       
   603 	my @xxx_remove;
       
   604 	my @xxx_add;
       
   605 	
       
   606 	# Separate the changes into lists of files for modify/add/remove
       
   607 	
       
   608 	foreach my $line (@$changes)
       
   609 		{
       
   610 		my $type = substr($line,0,2,"");	# removes type as well as extracting it
       
   611 		if ($type eq "M ")
       
   612 			{
       
   613 			push @xxx_modify, $line;
       
   614 			next;
       
   615 			}
       
   616 		if ($type eq "A " || $type eq "C ")
       
   617 			{
       
   618 			push @xxx_add, $line;
       
   619 			next;
       
   620 			}		
       
   621 		if ($type eq "R ")
       
   622 			{
       
   623 			push @xxx_remove, $line;
       
   624 			next;
       
   625 			}
       
   626 		
       
   627 		abandon_sync("Unexpected hg status line: $type$line");
       
   628 		}
       
   629 	
       
   630 	# Create an XXX system change object to record the changes (if necessary)
       
   631 	# process the lists of files
       
   632 	
       
   633 	if (scalar @xxx_add)
       
   634 		{
       
   635 		# add the files in the xxx_add list
       
   636 		}
       
   637 	
       
   638 	if (scalar @xxx_modify)
       
   639 		{
       
   640 		# process the list of modified files
       
   641 		}
       
   642 		
       
   643 	if (scalar @xxx_remove)
       
   644 		{
       
   645 		# remove the files in the xxx_remove list
       
   646 		}
       
   647 	
       
   648 	# Create the change description from the @$description list
       
   649 	
       
   650 	# Include the $hgnode as part of the description
       
   651 	# Use the $author and $date if possible (by might just have to be more descriptive text
       
   652 	# TODO: Do something with the interesting tags?
       
   653 	
       
   654 	my $scmref = some_function();
       
   655 	
       
   656 	return $scmref;
       
   657 	}