]>
Commit | Line | Data |
---|---|---|
e7f0d0d9 | 1 | git-p4 - Perforce <-> Git converter using git-fast-import |
0b69b469 SH |
2 | |
3 | Usage | |
4 | ===== | |
5 | ||
f5f7e4a1 SH |
6 | git-p4 can be used in two different ways: |
7 | ||
8 | 1) To import changes from Perforce to a Git repository, using "git-p4 sync". | |
9 | ||
10 | 2) To submit changes from Git back to Perforce, using "git-p4 submit". | |
0b69b469 SH |
11 | |
12 | Importing | |
13 | ========= | |
14 | ||
f5f7e4a1 | 15 | Simply start with |
f9a3a4f7 SH |
16 | |
17 | git-p4 clone //depot/path/project | |
18 | ||
19 | or | |
20 | ||
21 | git-p4 clone //depot/path/project myproject | |
22 | ||
f5f7e4a1 SH |
23 | This will: |
24 | ||
25 | 1) Create an empty git repository in a subdirectory called "project" (or | |
26 | "myproject" with the second command) | |
27 | ||
28 | 2) Import the head revision from the given Perforce path into a git branch | |
29 | called "p4" (remotes/p4 actually) | |
30 | ||
31 | 3) Create a master branch based on it and check it out. | |
32 | ||
33 | If you want the entire history (not just the head revision) then you can simply | |
34 | append a "@all" to the depot path: | |
f9a3a4f7 SH |
35 | |
36 | git-p4 clone //depot/project/main@all myproject | |
37 | ||
38 | ||
39 | ||
40 | If you want more control you can also use the git-p4 sync command directly: | |
0b69b469 SH |
41 | |
42 | mkdir repo-git | |
43 | cd repo-git | |
44 | git init | |
e7f0d0d9 | 45 | git-p4 sync //path/in/your/perforce/depot |
0b69b469 | 46 | |
f5816a55 | 47 | This will import the current head revision of the specified depot path into a |
81b462a6 | 48 | "remotes/p4/master" branch of your git repository. You can use the |
f5f7e4a1 | 49 | --branch=mybranch option to import into a different branch. |
0b69b469 | 50 | |
f5f7e4a1 | 51 | If you want to import the entire history of a given depot path simply use: |
0b69b469 | 52 | |
e7f0d0d9 | 53 | git-p4 sync //path/in/depot@all |
0b69b469 | 54 | |
f5f7e4a1 SH |
55 | |
56 | Note: | |
57 | ||
b4aa8d12 SH |
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. | |
0b69b469 | 60 | |
0b69b469 SH |
61 | Incremental Imports |
62 | =================== | |
63 | ||
f5f7e4a1 SH |
64 | After an initial import you can continue to synchronize your git repository |
65 | with newer changes from the Perforce depot by just calling | |
0b69b469 | 66 | |
179caebf | 67 | git-p4 sync |
0b69b469 | 68 | |
81b462a6 | 69 | in your git repository. By default the "remotes/p4/master" branch is updated. |
0b69b469 | 70 | |
f5f7e4a1 SH |
71 | Advanced Setup |
72 | ============== | |
73 | ||
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. | |
80 | ||
81 | This behaviour can be disabled by setting the "git-p4.syncFromOrigin" git | |
82 | configuration variable to "false". | |
b4aa8d12 | 83 | |
01ce1fe9 SH |
84 | Updating |
85 | ======== | |
86 | ||
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 | |
90 | ||
91 | git-p4 rebase | |
92 | ||
93 | command that calls git-p4 sync followed by git rebase to rebase the current | |
94 | working branch. | |
95 | ||
0b69b469 SH |
96 | Submitting |
97 | ========== | |
98 | ||
c9b50e63 | 99 | git-p4 has support for submitting changes from a git repository back to the |
f5f7e4a1 | 100 | Perforce depot. This requires a Perforce checkout separate from your git |
c9b50e63 SH |
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 | |
0b69b469 | 103 | |
9512497b | 104 | git-p4 submit |
0b69b469 | 105 | |
c9b50e63 SH |
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: | |
0b69b469 | 108 | |
c9b50e63 SH |
109 | git-p4 submit mytopicbranch |
110 | ||
111 | You can override the reference branch with the --origin=mysourcebranch option. | |
0b69b469 SH |
112 | |
113 | If a submit fails you may have to "p4 resolve" and submit manually. You can | |
114 | continue importing the remaining changes with | |
115 | ||
9512497b | 116 | git-p4 submit --continue |
0b69b469 | 117 | |
7243b350 SH |
118 | Example |
119 | ======= | |
120 | ||
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 | |
136 | ||
137 | ||
bc02acfc AK |
138 | Configuration parameters |
139 | ======================== | |
140 | ||
b87a6596 AK |
141 | git-p4.user ($P4USER) |
142 | ||
143 | Allows you to specify the username to use to connect to the Perforce repository. | |
144 | ||
145 | git config [--global] git-p4.user public | |
146 | ||
147 | git-p4.password ($P4PASS) | |
148 | ||
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. | |
151 | ||
152 | git config [--global] git-p4.password public1234 | |
153 | ||
154 | git-p4.port ($P4PORT) | |
155 | ||
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. | |
158 | ||
159 | git config [--global] git-p4.port codes.zimbra.com:2666 | |
160 | ||
161 | git-p4.host ($P4HOST) | |
162 | ||
163 | Specify the host to contact for a Perforce repository. | |
164 | ||
165 | git config [--global] git-p4.host perforce.example.com | |
166 | ||
167 | git-p4.client ($P4CLIENT) | |
168 | ||
169 | Specify the client name to use | |
170 | ||
171 | git config [--global] git-p4.client public-view | |
172 | ||
5b5aa22f AK |
173 | git-p4.allowSubmit |
174 | ||
175 | git config [--global] git-p4.allowSubmit false | |
176 | ||
bc02acfc AK |
177 | git-p4.syncFromOrigin |
178 | ||
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: | |
187 | ||
188 | git config [--global] git-p4.syncFromOrigin false | |
189 | ||
5b5aa22f AK |
190 | git-p4.useclientspec |
191 | ||
192 | git config [--global] git-p4.useclientspec false | |
193 | ||
a844b740 SH |
194 | Implementation Details... |
195 | ========================= | |
196 | ||
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. | |
a396b292 | 209 | The commits themselves are applied using git diff/format-patch ... | git apply |
a844b740 | 210 |