Put some documentation in about the parameters that have been added
[git/git.git] / contrib / fast-import / git-p4.txt
CommitLineData
e7f0d0d9 1git-p4 - Perforce <-> Git converter using git-fast-import
0b69b469
SH
2
3Usage
4=====
5
6git-p4 supports two main modes: Importing from Perforce to a Git repository is
ff5dba20
SH
7done using "git-p4 sync" or "git-p4 rebase". Submitting changes from Git back
8to Perforce is done using "git-p4 submit".
0b69b469
SH
9
10Importing
11=========
12
f9a3a4f7
SH
13You can simply start with
14
15 git-p4 clone //depot/path/project
16
17or
18
19 git-p4 clone //depot/path/project myproject
20
21This will create an empty git repository in a subdirectory called "project" (or
22"myproject" with the second command), import the head revision from the
c6d44cb1
SH
23specified perforce path into a git "p4" branch (remotes/p4 actually), create a
24master branch off it and check it out. If you want the entire history (not just
25the head revision) then you can simply append a "@all" to the depot path:
f9a3a4f7
SH
26
27 git-p4 clone //depot/project/main@all myproject
28
29
30
31If you want more control you can also use the git-p4 sync command directly:
0b69b469
SH
32
33 mkdir repo-git
34 cd repo-git
35 git init
e7f0d0d9 36 git-p4 sync //path/in/your/perforce/depot
0b69b469 37
f5816a55 38This will import the current head revision of the specified depot path into a
81b462a6
SH
39"remotes/p4/master" branch of your git repository. You can use the
40--branch=mybranch option to use a different branch.
0b69b469
SH
41
42If you want to import the entire history of a given depot path just use
43
e7f0d0d9 44 git-p4 sync //path/in/depot@all
0b69b469 45
b4aa8d12
SH
46To achieve optimal compression you may want to run 'git repack -a -d -f' after
47a big import. This may take a while.
0b69b469
SH
48
49Support for Perforce integrations is still work in progress. Don't bother
50trying it unless you want to hack on it :)
51
0b69b469
SH
52Incremental Imports
53===================
54
55After an initial import you can easily synchronize your git repository with
56newer changes from the Perforce depot by just calling
57
179caebf 58 git-p4 sync
0b69b469 59
81b462a6 60in your git repository. By default the "remotes/p4/master" branch is updated.
0b69b469 61
b4aa8d12
SH
62It is recommended to run 'git repack -a -d -f' from time to time when using
63incremental imports to optimally combine the individual git packs that each
64incremental import creates through the use of git-fast-import.
65
01ce1fe9
SH
66Updating
67========
68
69A common working pattern is to fetch the latest changes from the Perforce depot
70and merge them with local uncommitted changes. The recommended way is to use
71git's rebase mechanism to preserve linear history. git-p4 provides a convenient
72
73 git-p4 rebase
74
75command that calls git-p4 sync followed by git rebase to rebase the current
76working branch.
77
0b69b469
SH
78Submitting
79==========
80
c9b50e63
SH
81git-p4 has support for submitting changes from a git repository back to the
82Perforce depot. This requires a Perforce checkout separate to your git
83repository. To submit all changes that are in the current git branch but not in
84the "p4" branch (or "origin" if "p4" doesn't exist) simply call
0b69b469 85
9512497b 86 git-p4 submit
0b69b469 87
c9b50e63
SH
88in your git repository. If you want to submit changes in a specific branch that
89is not your current git branch you can also pass that as an argument:
0b69b469 90
c9b50e63
SH
91 git-p4 submit mytopicbranch
92
93You can override the reference branch with the --origin=mysourcebranch option.
0b69b469
SH
94
95If a submit fails you may have to "p4 resolve" and submit manually. You can
96continue importing the remaining changes with
97
9512497b 98 git-p4 submit --continue
0b69b469 99
9512497b
SH
100After submitting you should sync your perforce import branch ("p4" or "origin")
101from Perforce using git-p4's sync command.
7243b350 102
a396b292
SH
103If you have changes in your working directory that you haven't committed into
104git yet but that you want to commit to Perforce directly ("quick fixes") then
105you do not have to go through the intermediate step of creating a git commit
106first but you can just call
107
108 git-p4 submit --direct
109
7243b350
SH
110
111Example
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
bc02acfc
AK
131Configuration parameters
132========================
133
b87a6596
AK
134git-p4.user ($P4USER)
135
136Allows you to specify the username to use to connect to the Perforce repository.
137
138 git config [--global] git-p4.user public
139
140git-p4.password ($P4PASS)
141
142Allows you to specify the password to use to connect to the Perforce repository.
143Warning this password will be visible on the command-line invocation of the p4 binary.
144
145 git config [--global] git-p4.password public1234
146
147git-p4.port ($P4PORT)
148
149Specify the port to be used to contact the Perforce server. As this will be passed
150directly 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
154git-p4.host ($P4HOST)
155
156Specify the host to contact for a Perforce repository.
157
158 git config [--global] git-p4.host perforce.example.com
159
160git-p4.client ($P4CLIENT)
161
162Specify the client name to use
163
164 git config [--global] git-p4.client public-view
165
bc02acfc
AK
166git-p4.syncFromOrigin
167
168A useful setup may be that you have a periodically updated git repository
169somewhere that contains a complete import of a Perforce project. That git
170repository can be used to clone the working repository from and one would
171import from Perforce directly after cloning using git-p4. If the connection to
172the Perforce server is slow and the working repository hasn't been synced for a
173while it may be desirable to fetch changes from the origin git repository using
174the efficient git protocol. git-p4 supports this setup by calling "git fetch origin"
175by default if there is an origin branch. You can disable this using:
176
177 git config [--global] git-p4.syncFromOrigin false
178
a844b740
SH
179Implementation Details...
180=========================
181
182* Changesets from Perforce are imported using git fast-import.
183* The import does not require anything from the Perforce client view as it just uses
184 "p4 print //depot/path/file#revision" to get the actual file contents.
185* Every imported changeset has a special [git-p4...] line at the
186 end of the log message that gives information about the corresponding
187 Perforce change number and is also used by git-p4 itself to find out
188 where to continue importing when doing incremental imports.
189 Basically when syncing it extracts the perforce change number of the
190 latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
191 to find out which changes need to be imported.
192* git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
193 and the current branch.
a396b292 194 The commits themselves are applied using git diff/format-patch ... | git apply
a844b740 195