Importing
=========
-The procedure is simple:
+You can simply start with
+
+ git-p4 clone //depot/path/project
+
+or
+
+ git-p4 clone //depot/path/project myproject
+
+This will create an empty git repository in a subdirectory called "project" (or
+"myproject" with the second command), import the head revision from the
+specified perforce path into a git "p4" branch, create a master branch off it
+and check it out. If you want the entire history (not just the head revision) then
+you can simply append a "@all" to the depot path:
+
+ git-p4 clone //depot/project/main@all myproject
+
+
+
+If you want more control you can also use the git-p4 sync command directly:
mkdir repo-git
cd repo-git
Support for Perforce integrations is still work in progress. Don't bother
trying it unless you want to hack on it :)
+For convenience there's also the git-p4 clone command that works similar to
+git-clone and combines the creation of the git repository with the the initial
+import and the branch setup
Incremental Imports
===================
git-p4 sync
-in your git repository.
+in your git repository. By default the "p4" branch is updated.
It is recommended to run 'git repack -a -d -f' from time to time when using
incremental imports to optimally combine the individual git packs that each
incremental import creates through the use of git-fast-import.
+Updating
+========
+
+A common working pattern is to fetch the latest changes from the Perforce depot
+and merge them with local uncommitted changes. The recommended way is to use
+git's rebase mechanism to preserve linear history. git-p4 provides a convenient
+
+ git-p4 rebase
+
+command that calls git-p4 sync followed by git rebase to rebase the current
+working branch.
+
Submitting
==========
-git-p4 has EXPERIMENTAL support for submitting changes from a git repository
-back to a Perforce depot. This requires a Perforce checkout separate to your
-git repository. All it should take is calling
+git-p4 has support for submitting changes from a git repository back to the
+Perforce depot. This requires a Perforce checkout separate to your git
+repository. To submit all changes that are in the current git branch but not in
+the "p4" branch (or "origin" if "p4" doesn't exist) simply call
git-p4 submit
-in your git repository. This will attempt to locate the perforce checkout
-corresponding to your imported depot path. By default the changes between your
-current branch and the "p4" branch will be submitted. If there is no "p4"
-branch the "origin" branch will be used as reference instead. You can override
-this with the --origin=mysourcebranch option. The "origin" branch has to be the
-branch populated with git-p4's sync operation.
+in your git repository. If you want to submit changes in a specific branch that
+is not your current git branch you can also pass that as an argument:
-After some preparations (which might take a while) git-p4 enters a loop where
-it will first show a Perforce submit template and a diff of the change to
-apply in the editor. After saving and exiting the editor you will be asked whether
-you really want to submit the change or not.
+ git-p4 submit mytopicbranch
+
+You can override the reference branch with the --origin=mysourcebranch option.
If a submit fails you may have to "p4 resolve" and submit manually. You can
continue importing the remaining changes with
After submitting you should sync your perforce import branch ("p4" or "origin")
from Perforce using git-p4's sync command.
+
+Example
+=======
+
+# Clone a repository
+ git-p4 clone //depot/path/project
+# Enter the newly cloned directory
+ cd project
+# Do some work...
+ vi foo.h
+# ... and commit locally to gi
+ git commit foo.h
+# In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
+# changes against the latest changes in Perforce:
+ git-p4 rebase
+# Submit your locally committed changes back to Perforce
+ git-p4 submit
+# ... and synchronize with Perforce
+ git-p4 rebase
+
+