Perforce Public Knowledge Base - Git Fusion Quickstart Guide
Perforce Software logo
Reset Search



Git Fusion Quickstart Guide

« Go Back


Is there is step-by-step process for setting up Git Fusion?

1. Installation

  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 the OVA, update  p4gf_environment.cfg (or .git-fusion-profile if you are using an older version of Git Fusion) in the 'git' user's home directory.  See the detailed instructions:

       Connecting the Git Fusion OVA installation to your Perforce service.
   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.
  $ --set-version-counter P4PORT

  For more information on the atomic push trigger, see Troubleshooting

3. Git User Authentication

  Git Fusion supports SSH and HTTP authentication protocols.
 SSH Authentication
   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 Authentication

  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 ( 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
  User lookup
  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.
  1.    Search //.git-fusion/users/p4gf_usermap
  2.    Search user specs for a match (p4 users)
  3.    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 users are subject to Perforce protections on pushes, and optionally on pulls (see 'read-permission-check' in the global config file).

      Configuring global defaults for repos
  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@localhost:/Users/git/gitserve/project.git (fetch)
git@localhost:/Users/git/gitserve/project.git (push)
git@p4gf_test:gitimport (fetch)
git@p4gf_test:gitimport (push)

$ 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
Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255