git-p4 — any great explanations for how it works

Question

If you use perforce remotely and desire to have the awesome speed of git for tracking diffs, here is the solution: http://kb.perforce.com/article/1417/git-p4

However, I've noticed the following:

1. Follow the instructions exactly
2. It can take a while to import a large tree without getting history
3. On a large tree, the first commit will take a long time as this command will sync the whole tree.
4. If you do a commit that you do not want to send to perforce, you have to do a "git rebase -i" and remove the offending commit record. You cannot do a "git p4 submit" and then "p4 revert" the file you don't want to send.
5. If you mess something up, things can get really confusing.

And that is my question. Is there a good explanation of how git-p4 uses the remote repositories? And an overall explanation of hot git-p4 works?

git-p4 is not for the faint-at-heart. I'm learning that you really need to understand git well in order to use it well.

Answer 1

There is some more information in Documentation/git-p4.txt in the git project source code.

git-p4 maintains a refs/remotes/p4 branch to mirror the remote Perforce server. By default git-p4 clone and git-p4 sync update this remote and you rebase your master against it.

git-p4 submit requires configuring an additional local directory as the Perforce client root for use by p4 submit.

git-p4 sync/clone will record each Perforce changelist number in the corresponding git commit message. For example:

[git-p4: depot-paths = "//depot/test/": change = 51]

Using these changelist notations, git-p4 sync acquires changelists on the Perforce server not yet committed to git, adding changelist notations to each new git commit message.

git-p4 submit begins by identifying new local git commits - those without [git-p4: ...]. Using the Perforce client local workspace, it syncs down the Perforce files, and with git apply applies the patches gotten from git format-patch on the unsubmitted git commits before calling p4 submit.

Then git-p4 submit calls git-p4 sync to update the ref/remotes/p4 branch against the just updated Perforce remote.

Finally git-p4 submit will call git rebase on the master branch against the updated remote. This results in the same git tree which was submitted, but with edited commit messages containing the [git-p4...] changelist notations.

How does one keep a few files modified in git without ever sending them to p4?

git-p4 submit will submit all branch commits. Use the usual git tools to organize changes into and out of the branch you choose to submit to Perforce.

Answer 2

Regarding "What commits are pending to commit to perforce?"

Any command that can accept a revision range (see gitrevisions(7)) should work, you just have to refer to the p4 remote as an endpoint for the range. For instance:

• git log remotes/p4/master..master
• git diff remotes/p4/master..master

I tend to use show-branch to get a quick overview of the state of my branches, in which case git show-branch --all works as well.

Answer 3

I use git-p4 occasionally, as I travel frequently and don't always have a good connection to the office. My understanding, although I've not dived into it deeply, is that git-p4 maintains a Perforce workspace for you. Whenever you do a git p4 rebase, you're basically syncing code into your workspace, which git-p4 then replays as new commits into your git repository. Whenever you do a git p4 submit, it replays a series of patches into your Perforce workspace and submits them using Perforce changelists.

I guess you can think of it as using a Perforce server as a remote branch, but realistically it's a very limited implementation of that.

If you have more detailed questions, I'd try posting on the Perforce forums. There are a couple of folks in the office who have studied git-p4 in detail and might be able to help.

Answer 4

First Documentation/git-p4.txt has changed quite a lot in 8 years: See the diff between 2012 and Q1 2020.

• you can specify a single commit or a range of commits on git p4 submit
• you can use --shelve and --update-shelve to shelve changes instead of submitting
• you can import labels from p4 into Git.
• you can export tags from Git as p4 label.

But regarding "how it works", there are now helpers:

• you have a verbose mode which will help you see what is going on
• you have a dry-run mode, which shows just what commits would be submitted to p4; do not change state in Git or p4.

And with Git 2.25 (Q1 2020), the usage is displayed.

See commit 608e380, commit e2aed5f (16 Dec 2019) by Ben Keene (seraphire).
^{(Merged by Junio C Hamano -- gitster -- in commit bc85523, 02 Jan 2020)}

git-p4: show detailed help when parsing options fail

^{Signed-off-by: Ben Keene}

When a user provides invalid parameters to git-p4, the program reports the failure but does not provide the correct command syntax.

Add an exception handler to the command-line argument parser to display the command's specific command line parameter syntax when an exception is thrown.
Rethrow the exception so the current behavior is retained.

Answer 5

Perhaps you will find this alternative tool interesting: http://lm1.github.io/git-p4s

This is a fork of the original git-p4 utility with support for Perforce streams however only one-way sync works at this point.