1 git-p4 - Perforce <-> Git converter using git-fast-import
6 git-p4 supports two main modes: Importing from Perforce to a Git repository is
7 done using "git-p4 sync" or "git-p4 rebase". Submitting changes from Git back
8 to Perforce is done using "git-p4 submit".
13 You can simply start with
15 git-p4 clone //depot/path/project
19 git-p4 clone //depot/path/project myproject
21 This will create an empty git repository in a subdirectory called "project" (or
22 "myproject" with the second command), import the head revision from the
23 specified perforce path into a git "p4" branch (remotes/p4 actually), create a
24 master branch off it and check it out. If you want the entire history (not just
25 the head revision) then you can simply append a "@all" to the depot path:
27 git-p4 clone //depot/project/main@all myproject
31 If you want more control you can also use the git-p4 sync command directly:
36 git-p4 sync //path/in/your/perforce/depot
38 This will import the current head revision of the specified depot path into a
39 "p4" branch of your git repository. You can use the --branch=mybranch option
40 to use a different branch.
42 If you want to import the entire history of a given depot path just use
44 git-p4 sync //path/in/depot@all
46 To achieve optimal compression you may want to run 'git repack -a -d -f' after
47 a big import. This may take a while.
49 Support for Perforce integrations is still work in progress. Don't bother
50 trying it unless you want to hack on it :)
55 After an initial import you can easily synchronize your git repository with
56 newer changes from the Perforce depot by just calling
60 in your git repository. By default the "p4" branch is updated.
62 It is recommended to run 'git repack -a -d -f' from time to time when using
63 incremental imports to optimally combine the individual git packs that each
64 incremental import creates through the use of git-fast-import.
67 A useful setup may be that you have a periodically updated git repository
68 somewhere that contains a complete import of a Perforce project. That git
69 repository can be used to clone the working repository from and one would
70 import from Perforce directly after cloning using git-p4. If the connection to
71 the Perforce server is slow and the working repository hasn't been synced for a
72 while it may be desirable to fetch changes from the origin git repository using
73 the efficient git protocol. git-p4 supports this through
75 git-p4 sync --with-origin
79 git-p4 rebase --with-origin
81 In that case "git fetch origin" is called and if it turns out that the origin
82 branch is newer than the git "p4" import branch then the latter is updated from
83 the former and the direct import from Perforce is resumed, which will result in
84 fewer changes to be imported using the slower perforce connection.
89 A common working pattern is to fetch the latest changes from the Perforce depot
90 and merge them with local uncommitted changes. The recommended way is to use
91 git's rebase mechanism to preserve linear history. git-p4 provides a convenient
95 command that calls git-p4 sync followed by git rebase to rebase the current
101 git-p4 has support for submitting changes from a git repository back to the
102 Perforce depot. This requires a Perforce checkout separate to your git
103 repository. To submit all changes that are in the current git branch but not in
104 the "p4" branch (or "origin" if "p4" doesn't exist) simply call
108 in your git repository. If you want to submit changes in a specific branch that
109 is not your current git branch you can also pass that as an argument:
111 git-p4 submit mytopicbranch
113 You can override the reference branch with the --origin=mysourcebranch option.
115 If a submit fails you may have to "p4 resolve" and submit manually. You can
116 continue importing the remaining changes with
118 git-p4 submit --continue
120 After submitting you should sync your perforce import branch ("p4" or "origin")
121 from Perforce using git-p4's sync command.
128 git-p4 clone //depot/path/project
129 # Enter the newly cloned directory
133 # ... and commit locally to gi
135 # In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
136 # changes against the latest changes in Perforce:
138 # Submit your locally committed changes back to Perforce
140 # ... and synchronize with Perforce
144 Implementation Details...
145 =========================
147 * Changesets from Perforce are imported using git fast-import.
148 * The import does not require anything from the Perforce client view as it just uses
149 "p4 print //depot/path/file#revision" to get the actual file contents.
150 * Every imported changeset has a special [git-p4...] line at the
151 end of the log message that gives information about the corresponding
152 Perforce change number and is also used by git-p4 itself to find out
153 where to continue importing when doing incremental imports.
154 Basically when syncing it extracts the perforce change number of the
155 latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
156 to find out which changes need to be imported.
157 * git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
158 and the current branch.
159 The commits themselves are applied using git diff-tree ... | patch -p1