Configuring global defaults for repos

The User and Client Initialization script ( p4gf_init.py) creates the global configuration file and stores it in Helix Core at //.git-fusion/p4gf_config. You can edit any of its key values that you want repo configuration files to inherit by default.

Note

You can run this script any time after Git Fusion has been initialized in your Perforce service with the Super User Initialization script ( p4gf_super_init.py). If p4gf_init.py has not been run, p4gf_init_repo.py will invoke it automatically. If neither has been run, the first push or clone against this Git Fusion server will invoke them both automatically.

View the file header comments or see the table below for details.

Table 2. Global configuration file: keys and default values

Section Headers or Keys Definition Default Value Valid Values
[repo-creation] Section header for settings that control how Git Fusion creates new repos. NA Enter the section header exactly as shown.
charset Defines the default Unicode setting that Git Fusion applies to new repos. This setting is valid only when Git Fusion interacts with a Unicode-enabled Helix server. charset: UTF-8 Any P4CHARSET value; run p4 help charset for a list of valid values.
depot-path-repo-creation-enable Allow Git users to create new repos by pushing/pulling a git url which specifies a Helix Core depot path. This is similar to creating a repo from a p4 client. no

Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False).

No: Automatic repo creation from a depot path is disallowed.

Yes: Automatic repo creation from a depot path is allowed. Under the following conditions a new repo will be created:

  • The repo name is formated as: depotname/reponame/branchname

  • depotname is a defined Helix Core depot of type='local'

  • No p4gf_config nor p4 client exists with the translated name: depotname_0xS_reponame_0xS_branchname

If the conditions are not met, the push/pull will fail with the expected error message reporting the repo is not defined.

The newly created repo p4gf_config will contain:

[@repo] description = Created from 'depotname_0xS_reponame_0xS_branchname'

[Hzb5rdffTRGEsjotvTLoHg==]
git-branch-name = master
view = //depotname/reponame/branchname/... ... 

For a clone/pull situation, any files under //depotname/repo/branch will be imported into a new Git repo's master branch.

For a push situation, any files in the pushed Git branch will be imported into a new Perforce depot path.

depot-path-repo-creation-p4group

Restrict which authenticated Git pushers are allowed to create new repos when depot-path-repo-creation-enable is enabled.

 

Unset/None

Unset/None: No restriction: all Git pushers can create new repos from depot paths if depot-path-repo-creation-enable is enabled.

Set this to the name of an existing Perforcep4 group to restrict this feature to members of that group.

You can also use p4 protect to grant/deny write permission to areas of the Perforce depot.

[git-to-perforce] Section header for settings that define how Git commits are converted to Helix Core changes (submits). NA Enter the section header exactly as shown.
change-owner Defines whether Git Fusion assigns either the Git commit author or the Git pusher as the owner of a pushed change (submit). author Either author or pusher.
enable-git-branch-creation Defines whether Git Fusion creates a new branch of Helix Core depot file hierarchy for each copied branch of Git workspace history, including Git task branches as Git Fusion anonymous branches. See global configuration file for more information about setting this key. Yes

Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). When set to No, Git Fusion prohibits the copy of any new Git branches to Helix Core that are not defined in the repo’s configuration file, and also translates Perforce file hierarchy merges to Git as file edits, not as Git merge commits. However, Git Fusion will still copy Git merge commits between Helix Core branches that are defined in the repo's configuration file.

To permit Git Fusion to create new branches for Swarm reviews, you must also enable enable-swarm-reviews.

enable-swarm-reviews Permits branch creation for Swarm reviews, even when enable-git-branch-creation is disabled. See Using Swarm for code review for more information about Swarm reviews. Yes

Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). Yes enables Git Fusion to create a new branch of Helix Core depot file hierarchy for each new Swarm review and permits merge commits in the review history, which become anonymous branches in Helix Core.

This setting overrides enable-git-branch-creation and enable-git-merge-commits for Swarm reviews.

No disables the creation of branches for Swarm reviews, effectively disabling the ability to push Swarm reviews from Git.

enable-git-merge-commits Defines whether Git Fusion copies merge commits and displays them in Helix Core as integrations between Helix Core branches. See global configuration file for more information about setting this key. Yes

Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). No means that Git Fusion rejects all merge commits; integrations and merges between Helix Core branches must be performed using Helix Core.

enable-git-submodules Defines whether Git Fusion allows Git submodules to be pushed to Helix Core. Yes Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). No prevents Git submodules from being introduced into Git Fusion. If any submodules have already been pushed to Git Fusion, they will be left intact and be reproduced through clone/pull.
ignore-author-permissions Defines whether Git Fusion evaluates both the author's and pusher's Helix Core write permissions during a push or evaluates only the pusher's permissions. No Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). When set to yes, Git Fusion evaluates only the pusher’s permissions.
preflight-commit Enables you to trigger preflight commit scripts that enforce local policy for Git pushes. This can be especially useful if you have Helix Core submit triggers that could reject a push and damage the repository. For more information about setting this key, see Adding preflight commits to reject pushes. none

Pass passes all pushes that Git Fusion would otherwise permit, and Fail rejects all pushes; these values are primarily intended for temporarily disabling a preflight commit. You can add a path to a message as an argument to either of these values.

To enable a preflight commit script, use the syntax commandargument, where command is the path to the script. Arguments can include Git Fusion and Helix Core trigger variables, as in the following example:

preflight-commit = /home/git/myscript.sh %repo% %sha1%

preflight-push Enables you to trigger preflight push scripts that enforce local policy for Git pushes. This can be especially useful if you have Helix Core submit triggers that could reject a push and damage the repository. For more information about setting this key, see Adding preflight hooks to reject pushes. none

Pass passes all pushes that Git Fusion would otherwise permit, and Fail rejects all pushes; these values are primarily intended for temporarily disabling a preflight check. You can add a message as an argument to either of these values.

To enable a preflight push script, use the syntax command argument, where command is the path to the script. Arguments can include Git Fusion and Perforce trigger variables, as in the following example:

preflight-push = /home/git/myscript.sh %repo% %sha1%

read-permission-check Enables you to require that Git clone, pull, or fetch requests check the Helix Core protections table for the puller's read permission on the files being pulled. group Group bypasses a Helix Core permissions check on pull transactions, relying on membership in a Git Fusion pull permission group for access to the files. User enables a check that the puller's Helix Core user has Helix Core read permission for all files within the repo. For more information, see Enforce read permissions on Git pull.
git-merge-avoidance-after-change-num If the Perforce service includes any changelists submitted by Git Fusion 13.2 or earlier, you can prevent unnecessary merge commits by setting this key to the number of the last changelist submitted before your site upgraded to a later version of Git Fusion. p4 counter change

Keep the default value, p4 counter change, if you have no commits from earlier instances of Git Fusion (13.2 or earlier). At the first initialization of a Git Fusion repo, Git Fusion writes the changelist number to the global configuration file.

If you do have commits from Git Fusion 13.2 or earlier, provide the number of the the last changelist submitted before your site upgraded to a later version of Git Fusion.

job-lookup Set the format for entering Helix Core jobs in Git commit descriptions so that they are recognized by Git Fusion and appear in Helix Core changelists as fixes. By default, job IDs whose string starts with "job" (as in job123456) are passed through to the changelist description and job field. Use this option if you want Git Fusion to recognize additional expressions, such as JIRA issue IDs. For more information about including jobs in Git commit descriptions, see Referencing Helix Core jobs in a commit. none

Enter an expression that Git Fusion will pass to p4 jobs -e to look for matching jobs. You can add multiple fields, one per line.

For example, let's say your job specification includes the field DTG_DTISSUE for JIRA issue IDs. If you set job-lookup: DTG_DTISSUE={jobval}, then Git Fusion runs p4 jobs -e DTG_DTISSUE=XY-1234 when it sees a Git commit message that includes Jobs: XY-1234.

You do not need to add a value for standard Job IDs, stored in the job spec's Job field, whose string starts with "job" (as in job123456). These are passed through by default.

For more information about the p4 jobs command and the expressions that you can pass using -e, see the P4 Command Reference.

depot-branch-creation-enable

Allow Git users to create new fully-populated depot branches within Helix Core.

For more information, see Enabling Git users to create fully-populated branches

no

no: Any new branches pushed by Git users go into //.git-fusion/branches/ as lightweight depot branches.

explicit: Push to special remote branch reference depot-branch/branch_name. This creates a new fully-populated depot branch in Helix Core. For example, git push origin mybranch:depot-branch/research creates a new Helix Core depot branch under //depot/myrepo/research/.

all: Each new Git branch pushed by Git users goes into a new fully-populated depot branch in Helix Core. For example, git push origin mybranch:research creates a new Helix Core depot branch under //depot/myrepo/research/.

depot-branch-creation-p4group

Restrict the authenticated Git pushers who are allowed to create new fully-populated depot branches, if depot-branch-creation-enable is enabled.

For more information, see Enabling Git users to create fully-populated branches

None

Set to the name of an existing Helix Core p4 group to restrict this feature to members of that group.

Unset/None: No restriction. All Git pushers can create new fully-populated depot branches if depot-branch-creation-enable is enabled. You can unset this property and use the p4 protect command to fine-tune Helix Core user and group access to specific areas of the Helix Core depot.

depot-branch-creation-depot-path

Tell Git Fusion where to create new fully-populated depot branches, if depot-branch-creation-enable is enabled.

Default path is //depot/{repo}/{git_branch_name}

For more information, see Enabling Git users to create fully-populated branches

(at left)

Use the following string substitutions to set the location of new branches:

{repo}: returns the name of the Git Fusion repo receiving this push.

{git_branch_name} : returns the name of the pushed branch reference, such as, for example, myfeature in the command git push master:depot-branch/myfeature. Helix Core path rules apply: @, #, %, * , //, ... are prohibited; / is permitted. This substitution must be included somewhere in the string, or it becomes impossible for Git users to create more than one branch to a single repo.

{user}: returns the Helix Core user ID of the pusher.

depot-branch-creation-view

Set how the depot-path set in depot-branch-creation-depot-pathshould appear in Git.

For more information, see Enabling Git users to create fully-populated branches

... ...

Enter a Helix Core view specification that maps Helix Core depot paths (left side) to Git work tree paths (right side). Helix Core depot paths are relative to the root set in depot-branch-creation-depot-path.

The default "... ..." maps every file under the depot-branch-creation-depot-path root to Git. Right side paths must match the right side for every other branch already defined within a repo.

enable-git-find-copies

When Git reports a copy file action, store that action in Helix Core as a p4 integ. Often set in tandem with enable-git-find-renames.

For more information, see Detecting Git copy/rename and translating to Helix Core.

No

No/Off/0%: Do not use Git's copy detection. Treat all possible file copy actions as p4 add actions.

1%-100%: Use Git's copy detection. Value passed to git diff-tree --find-copies=n.

Git Fusion also adds --find-copies-harder whenever adding --find-copies.

enable-git-find-renames

When Git reports a rename (also called move) file action, store that in Helix Core as a p4 move. Often set in tandem with enable-git-find-copies.

For more information, see Detecting Git copy/rename and translating to Helix Core

No

No/Off/0%: Do not use Git's rename detection. Treat all possible file rename actions as independent p4 delete and p4 add actions.

1%-100%: Use Git's rename detection. Value passed to git diff-tree --find-renames=n.

[perforce-to-git] Section header for settings that define how Helix Core changes (submits) are converted to Git commits. NA Enter the section header exactly as shown.
enable-stream-imports

Enables you to convert Helix Core stream import paths to Git submodules when you clone a Git Fusion repository. If set to Yes, you must also set either http-url or ssh-url.

For more information, see Enabling stream import paths as Git submodules.

No Set to Yes equivalent (Yes, On, 1, True) to enable Git Fusion to convert compatible stream import paths to Git submodules. Set to No equivalent (No, Off, 0, False) to have import paths and their history incorporated in the Git repo for the stream.
http-url

The URL used by Git to clone a repository from Git Fusion over HTTP. This property is required if you want to use Helix Core stream import paths as git submodules and you use HTTP(S).

none

You can enter the full host name that you use to clone a repo from Git Fusion, or you can include variable placeholders that will be replaced by values from the Git Fusion environment:

{host}: returns the fully qualified hostname of the Git Fusion host computer, as fetched by the Linux function gethostname(). If this does not resolve to a value that is recognized by the client (a hostname that can be used to perform Git commands against the Git Fusion repos), then use the actual, full hostname rather than the variable.

{repo}: returns the name of the Git Fusion repository. Required, must be at the end of the string.

Example with only variable placeholders: http://{host}/{repo}

Example with hostname provided: http://p4gf.company.com/{repo}

For HTTPS installations, use the https:// prefix.

ssh-url The "URL" used by Git to clone a repository from Git Fusion using SSH. This property is required if you want to use Helix Core stream import paths as git submodules and you use SSH. none

You can use the following variable placeholders that will be replaced by values from the Git Fusion environment:

{user}: returns the SSH user performing the Git clone. If a user name is not found, this value defaults to git.

{host}: returns the fully qualified hostname of the Git Fusion host computer, as fetched by the Linux function gethostname(). If this does not resolve to a value that is recognized by the client (a hostname that can be used to perform Git commands against the Git Fusion repos), then use the actual, full hostname rather than the variable.

{repo}: returns the name of the Git Fusion repository. Required, must be at the end of the string.

Example with only variable placeholders: {user}@{host}:{repo}

Example with hostname provided: {user}@p4gf.company.com:{repo}

[authentication] Section header for settings that define authentication options. NA Enter the section header exactly as shown.
email-case-sensitivity Defines whether Git Fusion pays attention to case when matching Git user email addresses to Helix Core user account email addresses during the authorization check. For more information about how Git Fusion uses email addresses to authorize users, see Mapping Git users to Helix Core accounts. no

Yes equivalent (Yes, On, 1, True) or No equivalent (No, Off, 0, False). Yes enforces email address case sensitivity.

author-source Defines the source that Git Fusion uses to identify the Helix Core user associated with a Git push. For more information about how Git Fusion associates Git authors with Helix Core users, see Mapping Git users to Helix Core accounts. git-email

Use any one of the following values:

  • git-email: Use the email address of the Git author to look for a Helix Core user account with the same email address. Git Fusion consults the p4gf_usermap file first, and if that fails to produce a match, it scans the Helix Core user table.

  • git-user: Use the user.name field in the Git commit. This is the part of the author field before the email address.

  • git-email-account: Use the account portion of the Git author's email address. If the Git author's email value is <[email protected]_shire.com>, Git Fusion uses the Helix Core account samwise.

You can also tell Git Fusion to iterate through multiple source types until it finds a matching Perforce account. Specify the source types in order of precedence, separated by commas. For example: git-user, git-email-account, git-email.

[quota] Section header for settings that define push limit options. NA

Enter the section header exactly as shown.

limit_space_mb

Natural number representing the number of megabytes of disk space that can be consumed by any single repo. This value does not include the spaced consumed on the Helix server.

0

If the value is zero or less, the limit is not enforced.

limit_commits_received

Natural number representing the maximum number of commits allowed in a single push.

0

If the value is zero or less, the limit is not enforced.

limit_files_received

Natural number representing the maximum number of files allowed in a single push.

0

If the value is zero or less, the limit is not enforced.

limit_megabytes_received

Natural number representing the maximum number of megabytes allowed in a single push.

0

If the value is zero or less, the limit is not enforced.

The table below shows how the values you select for the enable-git-branch-creation and enable-git-merge-commits keys affect Git users' ability to perform branches and merges. Inform your Git users if you implement Scenarios 2, 3, or 4, because these scenarios will restrict their normal use of Git's branch and merge functionality.

Table 3. Git branch and merge: effect of configuration key values

Scenario enable-git-branch-creation Value enable-git-merge-commits Value Result
1 Yes Yes This scenario has the least impact on Git users' usual workflow. Any Git user with a corresponding valid Helix Core user (either his or her own user or unknown_git) can create and push branches and merge commits as they normally do in Git.
2 No No This is the most restrictive scenario for Git users. They cannot push any new Git branches that are not expressly defined in a repo's configuration file, and also must ensure that they push commits that have a linear history.
3 Yes No This scenario has a moderate impact on Git users. They can push new Git branches to Helix Core but they must ensure that all commits have a linear history. If they attempt to push a merge commit, Git Fusion displays the error message: remote: Merge commits are not enabled for this repo. Only Helix Core users can perform merge and integration work using a Helix Core workspace.
4 No Yes This scenario has a moderate impact on Git users. They can push merge commits between Helix Core branches that are defined in a repo's configuration file, but cannot push new Git branches to Helix Core. If they attempt to push a new Git branch, Git Fusion displays the error message: remote: Git branch creation is prohibited for this repo.