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.