Code

bash: improve aliased command recognition
[git.git] / contrib / fast-import / git-p4.txt
1 git-p4 - Perforce <-> Git converter using git-fast-import
3 Usage
4 =====
6 git-p4 can be used in two different ways:
8 1) To import changes from Perforce to a Git repository, using "git-p4 sync".
10 2) To submit changes from Git back to Perforce, using "git-p4 submit".
12 Importing
13 =========
15 Simply start with
17   git-p4 clone //depot/path/project
19 or
21   git-p4 clone //depot/path/project myproject
23 This will:
25 1) Create an empty git repository in a subdirectory called "project" (or
26 "myproject" with the second command)
28 2) Import the head revision from the given Perforce path into a git branch
29 called "p4" (remotes/p4 actually)
31 3) Create a master branch based on it and check it out.
33 If you want the entire history (not just the head revision) then you can simply
34 append a "@all" to the depot path:
36   git-p4 clone //depot/project/main@all myproject
40 If you want more control you can also use the git-p4 sync command directly:
42   mkdir repo-git
43   cd repo-git
44   git init
45   git-p4 sync //path/in/your/perforce/depot
47 This will import the current head revision of the specified depot path into a
48 "remotes/p4/master" branch of your git repository. You can use the
49 --branch=mybranch option to import into a different branch.
51 If you want to import the entire history of a given depot path simply use:
53   git-p4 sync //path/in/depot@all
56 Note:
58 To achieve optimal compression you may want to run 'git repack -a -d -f' after
59 a big import. This may take a while.
61 Incremental Imports
62 ===================
64 After an initial import you can continue to synchronize your git repository
65 with newer changes from the Perforce depot by just calling
67   git-p4 sync
69 in your git repository. By default the "remotes/p4/master" branch is updated.
71 Advanced Setup
72 ==============
74 Suppose you have a periodically updated git repository somewhere, containing a
75 complete import of a Perforce project. This repository can be cloned and used
76 with git-p4. When updating the cloned repository with the "sync" command,
77 git-p4 will try to fetch changes from the original repository first. The git
78 protocol used with this is usually faster than importing from Perforce
79 directly.
81 This behaviour can be disabled by setting the "git-p4.syncFromOrigin" git
82 configuration variable to "false".
84 Updating
85 ========
87 A common working pattern is to fetch the latest changes from the Perforce depot
88 and merge them with local uncommitted changes. The recommended way is to use
89 git's rebase mechanism to preserve linear history. git-p4 provides a convenient
91   git-p4 rebase
93 command that calls git-p4 sync followed by git rebase to rebase the current
94 working branch.
96 Submitting
97 ==========
99 git-p4 has support for submitting changes from a git repository back to the
100 Perforce depot. This requires a Perforce checkout separate from your git
101 repository. To submit all changes that are in the current git branch but not in
102 the "p4" branch (or "origin" if "p4" doesn't exist) simply call
104     git-p4 submit
106 in your git repository. If you want to submit changes in a specific branch that
107 is not your current git branch you can also pass that as an argument:
109     git-p4 submit mytopicbranch
111 You can override the reference branch with the --origin=mysourcebranch option.
113 If a submit fails you may have to "p4 resolve" and submit manually. You can
114 continue importing the remaining changes with
116   git-p4 submit --continue
118 Example
119 =======
121 # Clone a repository
122   git-p4 clone //depot/path/project
123 # Enter the newly cloned directory
124   cd project
125 # Do some work...
126   vi foo.h
127 # ... and commit locally to gi
128   git commit foo.h
129 # In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
130 # changes against the latest changes in Perforce:
131   git-p4 rebase
132 # Submit your locally committed changes back to Perforce
133   git-p4 submit
134 # ... and synchronize with Perforce
135   git-p4 rebase
138 Configuration parameters
139 ========================
141 git-p4.user ($P4USER)
143 Allows you to specify the username to use to connect to the Perforce repository.
145   git config [--global] git-p4.user public
147 git-p4.password ($P4PASS)
149 Allows you to specify the password to use to connect to the Perforce repository.
150 Warning this password will be visible on the command-line invocation of the p4 binary.
152   git config [--global] git-p4.password public1234
154 git-p4.port ($P4PORT)
156 Specify the port to be used to contact the Perforce server. As this will be passed
157 directly to the p4 binary, it may be in the format host:port as well.
159   git config [--global] git-p4.port codes.zimbra.com:2666
161 git-p4.host ($P4HOST)
163 Specify the host to contact for a Perforce repository.
165   git config [--global] git-p4.host perforce.example.com
167 git-p4.client ($P4CLIENT)
169 Specify the client name to use
171   git config [--global] git-p4.client public-view
173 git-p4.allowSubmit
175   git config [--global] git-p4.allowSubmit false
177 git-p4.syncFromOrigin
179 A useful setup may be that you have a periodically updated git repository
180 somewhere that contains a complete import of a Perforce project. That git
181 repository can be used to clone the working repository from and one would
182 import from Perforce directly after cloning using git-p4. If the connection to
183 the Perforce server is slow and the working repository hasn't been synced for a
184 while it may be desirable to fetch changes from the origin git repository using
185 the efficient git protocol. git-p4 supports this setup by calling "git fetch origin"
186 by default if there is an origin branch. You can disable this using:
188   git config [--global] git-p4.syncFromOrigin false
190 git-p4.useclientspec
192   git config [--global] git-p4.useclientspec false
194 Implementation Details...
195 =========================
197 * Changesets from Perforce are imported using git fast-import.
198 * The import does not require anything from the Perforce client view as it just uses
199   "p4 print //depot/path/file#revision" to get the actual file contents.
200 * Every imported changeset has a special [git-p4...] line at the
201   end of the log message that gives information about the corresponding
202   Perforce change number and is also used by git-p4 itself to find out
203   where to continue importing when doing incremental imports.
204   Basically when syncing it extracts the perforce change number of the
205   latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
206   to find out which changes need to be imported.
207 * git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
208   and the current branch.
209   The commits themselves are applied using git diff/format-patch ... | git apply