Put in the two other configuration elements found in the source
[git/git.git] / contrib / fast-import / git-p4.txt
1 git-p4 - Perforce <-> Git converter using git-fast-import
2
3 Usage
4 =====
5
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".
9
10 Importing
11 =========
12
13 You can simply start with
14
15 git-p4 clone //depot/path/project
16
17 or
18
19 git-p4 clone //depot/path/project myproject
20
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:
26
27 git-p4 clone //depot/project/main@all myproject
28
29
30
31 If you want more control you can also use the git-p4 sync command directly:
32
33 mkdir repo-git
34 cd repo-git
35 git init
36 git-p4 sync //path/in/your/perforce/depot
37
38 This will import the current head revision of the specified depot path into a
39 "remotes/p4/master" branch of your git repository. You can use the
40 --branch=mybranch option to use a different branch.
41
42 If you want to import the entire history of a given depot path just use
43
44 git-p4 sync //path/in/depot@all
45
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.
48
49 Support for Perforce integrations is still work in progress. Don't bother
50 trying it unless you want to hack on it :)
51
52 Incremental Imports
53 ===================
54
55 After an initial import you can easily synchronize your git repository with
56 newer changes from the Perforce depot by just calling
57
58 git-p4 sync
59
60 in your git repository. By default the "remotes/p4/master" branch is updated.
61
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.
65
66 Updating
67 ========
68
69 A common working pattern is to fetch the latest changes from the Perforce depot
70 and merge them with local uncommitted changes. The recommended way is to use
71 git's rebase mechanism to preserve linear history. git-p4 provides a convenient
72
73 git-p4 rebase
74
75 command that calls git-p4 sync followed by git rebase to rebase the current
76 working branch.
77
78 Submitting
79 ==========
80
81 git-p4 has support for submitting changes from a git repository back to the
82 Perforce depot. This requires a Perforce checkout separate to your git
83 repository. To submit all changes that are in the current git branch but not in
84 the "p4" branch (or "origin" if "p4" doesn't exist) simply call
85
86 git-p4 submit
87
88 in your git repository. If you want to submit changes in a specific branch that
89 is not your current git branch you can also pass that as an argument:
90
91 git-p4 submit mytopicbranch
92
93 You can override the reference branch with the --origin=mysourcebranch option.
94
95 If a submit fails you may have to "p4 resolve" and submit manually. You can
96 continue importing the remaining changes with
97
98 git-p4 submit --continue
99
100 After submitting you should sync your perforce import branch ("p4" or "origin")
101 from Perforce using git-p4's sync command.
102
103 If you have changes in your working directory that you haven't committed into
104 git yet but that you want to commit to Perforce directly ("quick fixes") then
105 you do not have to go through the intermediate step of creating a git commit
106 first but you can just call
107
108 git-p4 submit --direct
109
110
111 Example
112 =======
113
114 # Clone a repository
115 git-p4 clone //depot/path/project
116 # Enter the newly cloned directory
117 cd project
118 # Do some work...
119 vi foo.h
120 # ... and commit locally to gi
121 git commit foo.h
122 # In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
123 # changes against the latest changes in Perforce:
124 git-p4 rebase
125 # Submit your locally committed changes back to Perforce
126 git-p4 submit
127 # ... and synchronize with Perforce
128 git-p4 rebase
129
130
131 Configuration parameters
132 ========================
133
134 git-p4.user ($P4USER)
135
136 Allows you to specify the username to use to connect to the Perforce repository.
137
138 git config [--global] git-p4.user public
139
140 git-p4.password ($P4PASS)
141
142 Allows you to specify the password to use to connect to the Perforce repository.
143 Warning this password will be visible on the command-line invocation of the p4 binary.
144
145 git config [--global] git-p4.password public1234
146
147 git-p4.port ($P4PORT)
148
149 Specify the port to be used to contact the Perforce server. As this will be passed
150 directly to the p4 binary, it may be in the format host:port as well.
151
152 git config [--global] git-p4.port codes.zimbra.com:2666
153
154 git-p4.host ($P4HOST)
155
156 Specify the host to contact for a Perforce repository.
157
158 git config [--global] git-p4.host perforce.example.com
159
160 git-p4.client ($P4CLIENT)
161
162 Specify the client name to use
163
164 git config [--global] git-p4.client public-view
165
166 git-p4.allowSubmit
167
168 git config [--global] git-p4.allowSubmit false
169
170 git-p4.syncFromOrigin
171
172 A useful setup may be that you have a periodically updated git repository
173 somewhere that contains a complete import of a Perforce project. That git
174 repository can be used to clone the working repository from and one would
175 import from Perforce directly after cloning using git-p4. If the connection to
176 the Perforce server is slow and the working repository hasn't been synced for a
177 while it may be desirable to fetch changes from the origin git repository using
178 the efficient git protocol. git-p4 supports this setup by calling "git fetch origin"
179 by default if there is an origin branch. You can disable this using:
180
181 git config [--global] git-p4.syncFromOrigin false
182
183 git-p4.useclientspec
184
185 git config [--global] git-p4.useclientspec false
186
187 Implementation Details...
188 =========================
189
190 * Changesets from Perforce are imported using git fast-import.
191 * The import does not require anything from the Perforce client view as it just uses
192 "p4 print //depot/path/file#revision" to get the actual file contents.
193 * Every imported changeset has a special [git-p4...] line at the
194 end of the log message that gives information about the corresponding
195 Perforce change number and is also used by git-p4 itself to find out
196 where to continue importing when doing incremental imports.
197 Basically when syncing it extracts the perforce change number of the
198 latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
199 to find out which changes need to be imported.
200 * git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
201 and the current branch.
202 The commits themselves are applied using git diff/format-patch ... | git apply
203