Git Fusion can be installed a few different ways. The install involves deploying Git Fusion's Python code, plus its dependencies, and preparing your Perforce service for Git Fusion.
Currently, Git Fusion is only supported in Linux platform. However, it is possible to connect a Linux Git Fusion to a Windows Perforce Service. But, you may need to consider the usual cross-platform issues between a Linux and Windows environment such as case-sensitivity and path length limitations.
2. Preparing your Perforce service for Git Fusion
To point Git Fusion at a Perforce Service of your own, set the P4PORT of the user running Git Fusion to your Perforce server's P4PORT. In most cases you update the environment for the 'git' Linux service account, but it is not required that this service account running Git Fusion be named 'git'.
If using an install script, or a package installer, you may update the sample p4gf_env_config.txt and/or .bashrc for the non-interactive profile used by the 'git' service user in a bash shell. See the steps 6 and 7 in the "Installation steps" for further information: Create the Git Fusion environment configuration file
Initialize the Perforce Service with the Git Fusion components. The following script must be run with a Perforce 'super' user account from the Git Fusion host. Don't forget to log in to Perforce with that Perforce 'super' account.
--user super --port P4PORT
If you using running this against a Windows Perforce Service, you see the following warning message: " The Perforce service's case-handling policy is not set to 'sensitive',
which means any files introduced via Git whose names differ only by case may
result in data loss or errors during push. It is strongly advised to set the
case-handling policy to 'sensitive'. To bypass this check, pass --ignore-case
when invoking this script.
If that is what you want to do, you can re-run the command as:
--user super --port P4PORT --ignore-case
The Git Fusion Guide has a configuration step called "Configure Git Fusion submit triggers in the Perforce service to support atomic pushes". This is very important in a production environment or if you are doing concurrency testing. However, if you are currently just doing a proof of concept or some light testing, you can skip this step for now, and come back to it later. If you skip it for now, you still have to set a counter so Git Fusion thinks the triggers are installed.
$ p4gf_submit_trigger.py --set-version-counter P4PORT
3. Git User Authentication
Git Fusion supports SSH and HTTP authentication protocols.
The following KB article tells you what you need to know.
More detail in the primary docs:
Potential gotcha: Git's implementation of SSH will always use the "id_rsa" private key in your client-side .ssh directory. If you named your key file something else, rename it to id_rsa. Another option is to use an SSH config file to tell it what file to use. Information on using an SSH config file can be found here:
SSH directory permissions are also particular.
HTTP is now pre-configured in OVA. If you are using an older version of OVA, you can configure it manually:
4. User Setup
Note: One of the preparation steps (p4gf_super_init.py) will create three special Perforce service users and one special Perforce normal user, all prefixed with git-fusion-*. If you are running a licensed Perforce Service, you can request a free background user license for "git-fusion-user" and also for the 'unknown_git' user account if needed: Request for Background User
By default, the author's email address associated with a given commit is used to look up the Perforce user account. It goes through the following sequence for each commit's user lookup.
- Search //.git-fusion/users/p4gf_usermap
- Search user specs for a match (p4 users)
- Use 'unknown_git' user if it exists
It is possible to configure Git Fusion to only consider the pusher when pushing. See 'ignore-author-permissions' for repo configuration files.
Git Fusion also uses permission groups. It first tries to look up the user in the repo permission groups, then tries the global group, then checks a counter (git-fusion-permission-group-default). Being a member a pull group allows the user to clone, pull, or fetch. Being a member of a push group gives permission to push as well as pull. By default, the counter is set to 'push', meaning permissions are wide open. Setting the counter to 'none' means users must be a member of a one of the groups to be able to access the repo at all.
5. Creating a Git Fusion repo
Questions to answer: Where will the content originate from? Is there a portion of a Perforce depot you want to expose as a Git repo? Or do you have Git repo you want to push into Perforce?
Content originates in Perforce
Determine a discreet view of your Perforce repository. A Git repo usually represents a particular project. Hint: Creating a single repo for all of your product lines with 10 years of history is probably not a good choice.
You must map one or more Perforce depot paths to at least one Git branch (often 'master'). You can use the client workspace method or the repo config file method to define the mapping of Git and Perforce branches. Your repo configuration can have one or more mapped branches, where a Git branch maps to one or more Perforce paths. Unmapped Git branches can be pushed to Perforce, but they are primarily maintained for use by the Git repo and not intended for Perforce users to access. Hint: If you want more than one mapped branch, use the config file.
While Git Fusion supports sharing depot paths across repos, in Git, resources shared by different repos, are generally maintained in their own repository. The separate projects can then use the shared repo by including it as a submodule or other means.
Content originates in a Git repo
You can use the client workspace method or the repo config file method to define the mapping of Git and Perforce branches.
Recall how user lookup
works. Will the author's email of every commit match a Perforce user? If you do not expect so, you might choose to create the 'unknown_git' user or set 'ignore-author-permissions' to 'True' and 'change-owner' to "pusher".
If you want more than one mapped branch, use the config file. Be especially thoughtful about what Git branches you want mapped to Perforce paths as only mapped branches are visible to Perforce users. Using the config file gives you the flexibility to use other non-default values in your repo configuration such as setting ignore-author-permissions and change-owner. Sample repo configuration files
Note: The Perforce paths mapped in the config file cannot have existing content. Target paths must be new paths in Perforce.
An example import. (Before pushing you must define the remote Git repo that will be the Git Fusion repo in the local Git environment.)
$ git remote add p4gf git@p4gf_test:gitimport
$ git remote -v
$ git push p4gf master
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 297 bytes, done.
Total 3 (delta 0), reused 3 (delta 0)
remote: Perforce: 100% (1/1) Copying changelists...
remote: Perforce: 100% (2/2) Adding new Git objects to Perforce...
remote: Perforce: Submitting new Git objects to Perforce...
To git@p4gf_test:gitimport * [new branch] master -> master