USAGE for trim_excess_metadata.sh version 2.1.3:

trim_excess_metadata.sh <ServerTag> [-L <log>] [-y] [-d|-D]

or

trim_excess_metadata.sh [-h|-man|-V]


DESCRIPTION:

	*** WARNING WARNING WARNING WARNING ***
	This script could be dangerous if misused. Point it only at non-production servers.

	This script trims P4 metadata after a filtered replica is used in a divestiture situation.

	It should be pointed to a a commit server that was recently promoted from a filtered forwarding
	replica.  The replication filtering cleaned up path-based data.  This cleans up additional 
	metadata.

	IMPORTANT: See FILES section below for required P4CONFIG files.

	Phase 0: Preflight Checks
	Phase 1: LDAP Disconnect and Cleanup
	Phase 2: Client Cleanup (viewless clients only)
	Phase 3: Branch Cleanup (viewless branches only)
	Phase 4: Label Cleanup (viewless labels only)
	Phase 5: Group Cleanup
	Phase 6: Shelved CL Cleanup
	Phase 7: User Cleanup
	Phase 8: Stream Cleanup (**NOT IMPLEMENTED**)
	Phase 9: Job and Fix Cleanup (**NOT IMPLEMENTED**)
	Phase 10: Submitted CL Cleanup (empty CLs only)
	Phase 11: Depot Cleanup (empty depots only)

OPERATOR TIPS:
	1. Run this script in Dry Run mode first. Verify the expected results before running it with -y for a Live Run.
	2. Have a HUGE amount of space available for P4JOURNAL bloat that occurs during metadata removal.

EXTRA MANUAL STEPS
	This script DOES NOT clean up the following, which must be handled manually:

	* Protections table cleanup.
	* Triggers table cleanup.
	* Extensions removal and associated extension depot obliteration and cert cleanup.

	Other spots may be missed as well. Review the results carefully.

OPTIONS:
 -y	Live operation mode. By default, this script runs in Dry Run/Preview mode,
	where commands affecting data are displayed but not executed.  Use '-y' to
	execute after previewing.

 -d     Display debugging messages.

 -D     Set extreme debugging verbosity.

LOGGING:
	This script is self-logging.  That is, output displayed on the screen
	is simultaneously captured in the log file.  Using redirection operators
	like '> log' or '2>&1' and using 'tee' are unnecessary (but harmless).

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message
 -V	Display version info for this script and its libraries.

FILES:
	== P4CONFIG Files

	This script requires P4CONFIG files to be in the current directory when
	this script starts, named .p4config.<ServerTag>

	This P4CONFIG file should contain values for P4PORT, P4USER, P4TICKETS,
	and if needed, P4TRUST. These should reference the targeted server,
	which is generally a commit server recently promoted from a filtered
	forwarding replica.

	== Keep Users File

	When removing users, any users that should NOT be remove must have the P4USER
	account name listed in a "keep users" file in the current directory when
	this script starts.  Users are listed one per line, with no leading or
	trailing white space. If a file named keep_users.<ServerTag>.txt exists, it will
	be used. Otherwise a file named keep_users.txt will be used.  So there can be
	a single set of users for each server tag, or each server tag can have its own
	set of users.

	For example, the keep_users.txt file may look like
	this:

	admin
	bruno
	perforce

	At the very least, the "keep users" file must contain one user with super
	access. This file is required and this script will abort during preflight checks if
	it does not exist.

	== Keep Clients, Branches, Groups and Labels Files.

	When removing clients, branches, groups, and labels, any of these that should
	NOT be remove must have their names listed in the appropriate file, one entry
	per line:

	* keep_branches.<ServerTag>.txt OR keep_branches.txt
	* keep_clients.<ServerTag>.txt OR keep_clients.txt
	* keep_groups.<ServerTag>.txt OR keep_groups.txt
	* keep_labels.<ServerTag>.txt OR keep_labels.txt

	These optional files must appear in the directory where this script starts to
	have effect. The name including <ServerTag> takes precedence if it exists,
	otherwise the script falls back to other file name.

	In addition to the explicit lists above, any client, branch, or label whose
	'Owner:' field names a user listed in the Keep Users file is preserved
	automatically.  This avoids deleting metadata belonging to users that are
	being kept.  Note: groups are NOT subject to this owner-based rule; groups
	are kept only if listed in the Keep Groups file.

EXAMPLES:
	Example 1: Dry Run for instance 17777
	echo p4admin > keep_users.17777.txt
	trim_excess_metadata.sh 17777

	Example 2: Live Run for instance 17777
	trim_excess_metadata.sh 17777 -y