Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 1 | git-p4(1) |
| 2 | ========= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-p4 - Import from and submit to Perforce repositories |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... |
| 13 | 'git p4 sync' [<sync options>] [<p4 depot path>...] |
| 14 | 'git p4 rebase' |
| 15 | 'git p4 submit' [<submit options>] [<master branch name>] |
| 16 | |
| 17 | |
| 18 | DESCRIPTION |
| 19 | ----------- |
| 20 | This command provides a way to interact with p4 repositories |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 21 | using Git. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 22 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 23 | Create a new Git repository from an existing p4 repository using |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 24 | 'git p4 clone', giving it one or more p4 depot paths. Incorporate |
| 25 | new commits from p4 changes with 'git p4 sync'. The 'sync' command |
| 26 | is also used to include new branches from other p4 depot paths. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 27 | Submit Git changes back to p4 using 'git p4 submit'. The command |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 28 | 'git p4 rebase' does a sync plus rebases the current branch onto |
| 29 | the updated p4 remote branch. |
| 30 | |
| 31 | |
| 32 | EXAMPLE |
| 33 | ------- |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 34 | * Clone a repository: |
| 35 | + |
| 36 | ------------ |
| 37 | $ git p4 clone //depot/path/project |
| 38 | ------------ |
| 39 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 40 | * Do some work in the newly created Git repository: |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 41 | + |
| 42 | ------------ |
| 43 | $ cd project |
| 44 | $ vi foo.h |
| 45 | $ git commit -a -m "edited foo.h" |
| 46 | ------------ |
| 47 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 48 | * Update the Git repository with recent changes from p4, rebasing your |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 49 | work on top: |
| 50 | + |
| 51 | ------------ |
| 52 | $ git p4 rebase |
| 53 | ------------ |
| 54 | |
| 55 | * Submit your commits back to p4: |
| 56 | + |
| 57 | ------------ |
| 58 | $ git p4 submit |
| 59 | ------------ |
| 60 | |
| 61 | |
| 62 | COMMANDS |
| 63 | -------- |
| 64 | |
| 65 | Clone |
| 66 | ~~~~~ |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 67 | Generally, 'git p4 clone' is used to create a new Git directory |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 68 | from an existing p4 repository: |
| 69 | ------------ |
| 70 | $ git p4 clone //depot/path/project |
| 71 | ------------ |
| 72 | This: |
| 73 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 74 | 1. Creates an empty Git repository in a subdirectory called 'project'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 75 | + |
| 76 | 2. Imports the full contents of the head revision from the given p4 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 77 | depot path into a single commit in the Git branch 'refs/remotes/p4/master'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 78 | + |
| 79 | 3. Creates a local branch, 'master' from this remote and checks it out. |
| 80 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 81 | To reproduce the entire p4 history in Git, use the '@all' modifier on |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 82 | the depot path: |
| 83 | ------------ |
| 84 | $ git p4 clone //depot/path/project@all |
| 85 | ------------ |
| 86 | |
| 87 | |
| 88 | Sync |
| 89 | ~~~~ |
| 90 | As development continues in the p4 repository, those changes can |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 91 | be included in the Git repository using: |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 92 | ------------ |
| 93 | $ git p4 sync |
| 94 | ------------ |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 95 | This command finds new changes in p4 and imports them as Git commits. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 96 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 97 | P4 repositories can be added to an existing Git repository using |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 98 | 'git p4 sync' too: |
| 99 | ------------ |
| 100 | $ mkdir repo-git |
| 101 | $ cd repo-git |
| 102 | $ git init |
| 103 | $ git p4 sync //path/in/your/perforce/depot |
| 104 | ------------ |
| 105 | This imports the specified depot into |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 106 | 'refs/remotes/p4/master' in an existing Git repository. The |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 107 | '--branch' option can be used to specify a different branch to |
| 108 | be used for the p4 content. |
| 109 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 110 | If a Git repository includes branches 'refs/remotes/origin/p4', these |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 111 | will be fetched and consulted first during a 'git p4 sync'. Since |
| 112 | importing directly from p4 is considerably slower than pulling changes |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 113 | from a Git remote, this can be useful in a multi-developer environment. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 114 | |
Pete Wyckoff | 8c9e8b6 | 2013-01-14 19:47:06 -0500 | [diff] [blame] | 115 | If there are multiple branches, doing 'git p4 sync' will automatically |
| 116 | use the "BRANCH DETECTION" algorithm to try to partition new changes |
| 117 | into the right branch. This can be overridden with the '--branch' |
| 118 | option to specify just a single branch to update. |
| 119 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 120 | |
| 121 | Rebase |
| 122 | ~~~~~~ |
| 123 | A common working pattern is to fetch the latest changes from the p4 depot |
| 124 | and merge them with local uncommitted changes. Often, the p4 repository |
| 125 | is the ultimate location for all code, thus a rebase workflow makes |
| 126 | sense. This command does 'git p4 sync' followed by 'git rebase' to move |
| 127 | local commits on top of updated p4 changes. |
| 128 | ------------ |
| 129 | $ git p4 rebase |
| 130 | ------------ |
| 131 | |
| 132 | |
| 133 | Submit |
| 134 | ~~~~~~ |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 135 | Submitting changes from a Git repository back to the p4 repository |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 136 | requires a separate p4 client workspace. This should be specified |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 137 | using the 'P4CLIENT' environment variable or the Git configuration |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 138 | variable 'git-p4.client'. The p4 client must exist, but the client root |
| 139 | will be created and populated if it does not already exist. |
| 140 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 141 | To submit all changes that are in the current Git branch but not in |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 142 | the 'p4/master' branch, use: |
| 143 | ------------ |
| 144 | $ git p4 submit |
| 145 | ------------ |
| 146 | |
| 147 | To specify a branch other than the current one, use: |
| 148 | ------------ |
| 149 | $ git p4 submit topicbranch |
| 150 | ------------ |
| 151 | |
| 152 | The upstream reference is generally 'refs/remotes/p4/master', but can |
| 153 | be overridden using the '--origin=' command-line option. |
| 154 | |
| 155 | The p4 changes will be created as the user invoking 'git p4 submit'. The |
| 156 | '--preserve-user' option will cause ownership to be modified |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 157 | according to the author of the Git commit. This option requires admin |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 158 | privileges in p4, which can be granted using 'p4 protect'. |
| 159 | |
| 160 | |
| 161 | OPTIONS |
| 162 | ------- |
| 163 | |
| 164 | General options |
| 165 | ~~~~~~~~~~~~~~~ |
Luke Diamand | 6a10b6a | 2012-04-24 09:33:23 +0100 | [diff] [blame] | 166 | All commands except clone accept these options. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 167 | |
| 168 | --git-dir <dir>:: |
| 169 | Set the 'GIT_DIR' environment variable. See linkgit:git[1]. |
| 170 | |
Pete Wyckoff | f84cb68 | 2014-01-21 18:16:48 -0500 | [diff] [blame] | 171 | -v:: |
| 172 | --verbose:: |
Luke Diamand | 6a10b6a | 2012-04-24 09:33:23 +0100 | [diff] [blame] | 173 | Provide more progress information. |
| 174 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 175 | Sync options |
| 176 | ~~~~~~~~~~~~ |
| 177 | These options can be used in the initial 'clone' as well as in |
| 178 | subsequent 'sync' operations. |
| 179 | |
Michael Schubert | d6ac1d2 | 2013-07-03 11:12:34 +0200 | [diff] [blame] | 180 | --branch <ref>:: |
| 181 | Import changes into <ref> instead of refs/remotes/p4/master. |
| 182 | If <ref> starts with refs/, it is used as is. Otherwise, if |
| 183 | it does not start with p4/, that prefix is added. |
| 184 | + |
| 185 | By default a <ref> not starting with refs/ is treated as the |
| 186 | name of a remote-tracking branch (under refs/remotes/). This |
| 187 | behavior can be modified using the --import-local option. |
| 188 | + |
| 189 | The default <ref> is "master". |
Pete Wyckoff | 1471c6b | 2011-12-24 21:07:34 -0500 | [diff] [blame] | 190 | + |
| 191 | This example imports a new remote "p4/proj2" into an existing |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 192 | Git repository: |
Pete Wyckoff | 41925d5 | 2012-05-06 11:58:38 -0400 | [diff] [blame] | 193 | + |
Pete Wyckoff | 1471c6b | 2011-12-24 21:07:34 -0500 | [diff] [blame] | 194 | ---- |
| 195 | $ git init |
| 196 | $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 |
| 197 | ---- |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 198 | |
| 199 | --detect-branches:: |
| 200 | Use the branch detection algorithm to find new paths in p4. It is |
| 201 | documented below in "BRANCH DETECTION". |
| 202 | |
| 203 | --changesfile <file>:: |
| 204 | Import exactly the p4 change numbers listed in 'file', one per |
| 205 | line. Normally, 'git p4' inspects the current p4 repository |
| 206 | state and detects the changes it should import. |
| 207 | |
| 208 | --silent:: |
| 209 | Do not print any progress information. |
| 210 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 211 | --detect-labels:: |
| 212 | Query p4 for labels associated with the depot paths, and add |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 213 | them as tags in Git. Limited usefulness as only imports labels |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 214 | associated with new changelists. Deprecated. |
| 215 | |
| 216 | --import-labels:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 217 | Import labels from p4 into Git. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 218 | |
| 219 | --import-local:: |
| 220 | By default, p4 branches are stored in 'refs/remotes/p4/', |
| 221 | where they will be treated as remote-tracking branches by |
| 222 | linkgit:git-branch[1] and other commands. This option instead |
Pete Wyckoff | 5a92a6c | 2011-12-24 21:07:36 -0500 | [diff] [blame] | 223 | puts p4 branches in 'refs/heads/p4/'. Note that future |
| 224 | sync operations must specify '--import-local' as well so that |
| 225 | they can find the p4 branches in refs/heads. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 226 | |
| 227 | --max-changes <n>:: |
| 228 | Limit the number of imported changes to 'n'. Useful to |
| 229 | limit the amount of history when using the '@all' p4 revision |
| 230 | specifier. |
| 231 | |
| 232 | --keep-path:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 233 | The mapping of file names from the p4 depot path to Git, by |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 234 | default, involves removing the entire depot path. With this |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 235 | option, the full p4 depot path is retained in Git. For example, |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 236 | path '//depot/main/foo/bar.c', when imported from |
| 237 | '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 238 | Git path is instead 'depot/main/foo/bar.c'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 239 | |
| 240 | --use-client-spec:: |
| 241 | Use a client spec to find the list of interesting files in p4. |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 242 | See the "CLIENT SPEC" section below. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 243 | |
Luke Diamand | 51334bb | 2015-01-17 20:56:38 +0000 | [diff] [blame^] | 244 | -/ <path>:: |
| 245 | Exclude selected depot paths when cloning or syncing. |
| 246 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 247 | Clone options |
| 248 | ~~~~~~~~~~~~~ |
| 249 | These options can be used in an initial 'clone', along with the 'sync' |
| 250 | options described above. |
| 251 | |
| 252 | --destination <directory>:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 253 | Where to create the Git repository. If not provided, the last |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 254 | component in the p4 depot path is used to create a new |
| 255 | directory. |
| 256 | |
| 257 | --bare:: |
| 258 | Perform a bare clone. See linkgit:git-clone[1]. |
| 259 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 260 | Submit options |
| 261 | ~~~~~~~~~~~~~~ |
| 262 | These options can be used to modify 'git p4 submit' behavior. |
| 263 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 264 | --origin <commit>:: |
| 265 | Upstream location from which commits are identified to submit to |
| 266 | p4. By default, this is the most recent p4 commit reachable |
| 267 | from 'HEAD'. |
| 268 | |
Gary Gibbons | 84cb000 | 2012-07-04 09:40:19 -0400 | [diff] [blame] | 269 | -M:: |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 270 | Detect renames. See linkgit:git-diff[1]. Renames will be |
Pete Wyckoff | 28755db | 2011-12-24 21:07:40 -0500 | [diff] [blame] | 271 | represented in p4 using explicit 'move' operations. There |
| 272 | is no corresponding option to detect copies, but there are |
| 273 | variables for both moves and copies. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 274 | |
| 275 | --preserve-user:: |
| 276 | Re-author p4 changes before submitting to p4. This option |
| 277 | requires p4 admin privileges. |
| 278 | |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 279 | --export-labels:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 280 | Export tags from Git as p4 labels. Tags found in Git are applied |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 281 | to the perforce working directory. |
| 282 | |
Pete Wyckoff | f84cb68 | 2014-01-21 18:16:48 -0500 | [diff] [blame] | 283 | -n:: |
| 284 | --dry-run:: |
Pete Wyckoff | ef739f0 | 2012-09-09 16:16:11 -0400 | [diff] [blame] | 285 | Show just what commits would be submitted to p4; do not change |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 286 | state in Git or p4. |
Pete Wyckoff | ef739f0 | 2012-09-09 16:16:11 -0400 | [diff] [blame] | 287 | |
Pete Wyckoff | 728b7ad | 2012-09-09 16:16:12 -0400 | [diff] [blame] | 288 | --prepare-p4-only:: |
| 289 | Apply a commit to the p4 workspace, opening, adding and deleting |
| 290 | files in p4 as for a normal submit operation. Do not issue the |
| 291 | final "p4 submit", but instead print a message about how to |
| 292 | submit manually or revert. This option always stops after the |
| 293 | first (oldest) commit. Git tags are not exported to p4. |
| 294 | |
Pete Wyckoff | 6bbfd13 | 2012-09-09 16:16:13 -0400 | [diff] [blame] | 295 | --conflict=(ask|skip|quit):: |
| 296 | Conflicts can occur when applying a commit to p4. When this |
| 297 | happens, the default behavior ("ask") is to prompt whether to |
| 298 | skip this commit and continue, or quit. This option can be used |
| 299 | to bypass the prompt, causing conflicting commits to be automatically |
| 300 | skipped, or to quit trying to apply commits, without prompting. |
| 301 | |
Pete Wyckoff | 44e8d26 | 2013-01-14 19:47:08 -0500 | [diff] [blame] | 302 | --branch <branch>:: |
| 303 | After submitting, sync this named branch instead of the default |
| 304 | p4/master. See the "Sync options" section above for more |
| 305 | information. |
| 306 | |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 307 | Rebase options |
| 308 | ~~~~~~~~~~~~~~ |
| 309 | These options can be used to modify 'git p4 rebase' behavior. |
| 310 | |
| 311 | --import-labels:: |
| 312 | Import p4 labels. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 313 | |
| 314 | DEPOT PATH SYNTAX |
| 315 | ----------------- |
| 316 | The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can |
| 317 | be one or more space-separated p4 depot paths, with an optional |
| 318 | p4 revision specifier on the end: |
| 319 | |
| 320 | "//depot/my/project":: |
| 321 | Import one commit with all files in the '#head' change under that tree. |
| 322 | |
| 323 | "//depot/my/project@all":: |
| 324 | Import one commit for each change in the history of that depot path. |
| 325 | |
| 326 | "//depot/my/project@1,6":: |
| 327 | Import only changes 1 through 6. |
| 328 | |
Pete Wyckoff | da191d1 | 2011-12-24 21:07:33 -0500 | [diff] [blame] | 329 | "//depot/proj1@all //depot/proj2@all":: |
| 330 | Import all changes from both named depot paths into a single |
| 331 | repository. Only files below these directories are included. |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 332 | There is not a subdirectory in Git for each "proj1" and "proj2". |
Pete Wyckoff | da191d1 | 2011-12-24 21:07:33 -0500 | [diff] [blame] | 333 | You must use the '--destination' option when specifying more |
| 334 | than one depot path. The revision specifier must be specified |
| 335 | identically on each depot path. If there are files in the |
| 336 | depot paths with the same name, the path with the most recently |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 337 | updated version of the file is the one that appears in Git. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 338 | |
| 339 | See 'p4 help revisions' for the full syntax of p4 revision specifiers. |
| 340 | |
| 341 | |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 342 | CLIENT SPEC |
| 343 | ----------- |
| 344 | The p4 client specification is maintained with the 'p4 client' command |
| 345 | and contains among other fields, a View that specifies how the depot |
Pete Wyckoff | a93d33e | 2012-02-25 20:06:24 -0500 | [diff] [blame] | 346 | is mapped into the client repository. The 'clone' and 'sync' commands |
| 347 | can consult the client spec when given the '--use-client-spec' option or |
| 348 | when the useClientSpec variable is true. After 'git p4 clone', the |
| 349 | useClientSpec variable is automatically set in the repository |
| 350 | configuration file. This allows future 'git p4 submit' commands to |
| 351 | work properly; the submit command looks only at the variable and does |
| 352 | not have a command-line option. |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 353 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 354 | The full syntax for a p4 view is documented in 'p4 help views'. 'git p4' |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 355 | knows only a subset of the view syntax. It understands multi-line |
| 356 | mappings, overlays with '+', exclusions with '-' and double-quotes |
Pete Wyckoff | b6f9305 | 2012-04-08 20:18:00 -0400 | [diff] [blame] | 357 | around whitespace. Of the possible wildcards, 'git p4' only handles |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 358 | '...', and only when it is at the end of the path. 'git p4' will complain |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 359 | if it encounters an unhandled wildcard. |
| 360 | |
Pete Wyckoff | 42d8c27 | 2012-01-11 18:31:10 -0500 | [diff] [blame] | 361 | Bugs in the implementation of overlap mappings exist. If multiple depot |
| 362 | paths map through overlays to the same location in the repository, |
Pete Wyckoff | b6f9305 | 2012-04-08 20:18:00 -0400 | [diff] [blame] | 363 | 'git p4' can choose the wrong one. This is hard to solve without |
| 364 | dedicating a client spec just for 'git p4'. |
Pete Wyckoff | 42d8c27 | 2012-01-11 18:31:10 -0500 | [diff] [blame] | 365 | |
Pete Wyckoff | b6f9305 | 2012-04-08 20:18:00 -0400 | [diff] [blame] | 366 | The name of the client can be given to 'git p4' in multiple ways. The |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 367 | variable 'git-p4.client' takes precedence if it exists. Otherwise, |
| 368 | normal p4 mechanisms of determining the client are used: environment |
| 369 | variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. |
| 370 | |
| 371 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 372 | BRANCH DETECTION |
| 373 | ---------------- |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 374 | P4 does not have the same concept of a branch as Git. Instead, |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 375 | p4 organizes its content as a directory tree, where by convention |
| 376 | different logical branches are in different locations in the tree. |
| 377 | The 'p4 branch' command is used to maintain mappings between |
| 378 | different areas in the tree, and indicate related content. 'git p4' |
| 379 | can use these mappings to determine branch relationships. |
| 380 | |
| 381 | If you have a repository where all the branches of interest exist as |
| 382 | subdirectories of a single depot path, you can use '--detect-branches' |
| 383 | when cloning or syncing to have 'git p4' automatically find |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 384 | subdirectories in p4, and to generate these as branches in Git. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 385 | |
| 386 | For example, if the P4 repository structure is: |
| 387 | ---- |
| 388 | //depot/main/... |
| 389 | //depot/branch1/... |
| 390 | ---- |
| 391 | |
| 392 | And "p4 branch -o branch1" shows a View line that looks like: |
| 393 | ---- |
| 394 | //depot/main/... //depot/branch1/... |
| 395 | ---- |
| 396 | |
| 397 | Then this 'git p4 clone' command: |
| 398 | ---- |
| 399 | git p4 clone --detect-branches //depot@all |
| 400 | ---- |
| 401 | produces a separate branch in 'refs/remotes/p4/' for //depot/main, |
| 402 | called 'master', and one for //depot/branch1 called 'depot/branch1'. |
| 403 | |
| 404 | However, it is not necessary to create branches in p4 to be able to use |
| 405 | them like branches. Because it is difficult to infer branch |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 406 | relationships automatically, a Git configuration setting |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 407 | 'git-p4.branchList' can be used to explicitly identify branch |
| 408 | relationships. It is a list of "source:destination" pairs, like a |
| 409 | simple p4 branch specification, where the "source" and "destination" are |
| 410 | the path elements in the p4 repository. The example above relied on the |
| 411 | presence of the p4 branch. Without p4 branches, the same result will |
| 412 | occur with: |
| 413 | ---- |
Pete Wyckoff | 182edef | 2013-01-14 19:47:02 -0500 | [diff] [blame] | 414 | git init depot |
| 415 | cd depot |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 416 | git config git-p4.branchList main:branch1 |
Pete Wyckoff | 182edef | 2013-01-14 19:47:02 -0500 | [diff] [blame] | 417 | git p4 clone --detect-branches //depot@all . |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 418 | ---- |
| 419 | |
| 420 | |
| 421 | PERFORMANCE |
| 422 | ----------- |
| 423 | The fast-import mechanism used by 'git p4' creates one pack file for |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 424 | each invocation of 'git p4 sync'. Normally, Git garbage compression |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 425 | (linkgit:git-gc[1]) automatically compresses these to fewer pack files, |
| 426 | but explicit invocation of 'git repack -adf' may improve performance. |
| 427 | |
| 428 | |
| 429 | CONFIGURATION VARIABLES |
| 430 | ----------------------- |
| 431 | The following config settings can be used to modify 'git p4' behavior. |
| 432 | They all are in the 'git-p4' section. |
| 433 | |
| 434 | General variables |
| 435 | ~~~~~~~~~~~~~~~~~ |
| 436 | git-p4.user:: |
| 437 | User specified as an option to all p4 commands, with '-u <user>'. |
| 438 | The environment variable 'P4USER' can be used instead. |
| 439 | |
| 440 | git-p4.password:: |
| 441 | Password specified as an option to all p4 commands, with |
| 442 | '-P <password>'. |
| 443 | The environment variable 'P4PASS' can be used instead. |
| 444 | |
| 445 | git-p4.port:: |
| 446 | Port specified as an option to all p4 commands, with |
| 447 | '-p <port>'. |
| 448 | The environment variable 'P4PORT' can be used instead. |
| 449 | |
| 450 | git-p4.host:: |
| 451 | Host specified as an option to all p4 commands, with |
| 452 | '-h <host>'. |
| 453 | The environment variable 'P4HOST' can be used instead. |
| 454 | |
| 455 | git-p4.client:: |
| 456 | Client specified as an option to all p4 commands, with |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 457 | '-c <client>', including the client spec. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 458 | |
| 459 | Clone and sync variables |
| 460 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 461 | git-p4.syncFromOrigin:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 462 | Because importing commits from other Git repositories is much faster |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 463 | than importing them from p4, a mechanism exists to find p4 changes |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 464 | first in Git remotes. If branches exist under 'refs/remote/origin/p4', |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 465 | those will be fetched and used when syncing from p4. This |
| 466 | variable can be set to 'false' to disable this behavior. |
| 467 | |
| 468 | git-p4.branchUser:: |
| 469 | One phase in branch detection involves looking at p4 branches |
| 470 | to find new ones to import. By default, all branches are |
| 471 | inspected. This option limits the search to just those owned |
| 472 | by the single user named in the variable. |
| 473 | |
| 474 | git-p4.branchList:: |
| 475 | List of branches to be imported when branch detection is |
| 476 | enabled. Each entry should be a pair of branch names separated |
| 477 | by a colon (:). This example declares that both branchA and |
| 478 | branchB were created from main: |
Pete Wyckoff | 41925d5 | 2012-05-06 11:58:38 -0400 | [diff] [blame] | 479 | + |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 480 | ------------- |
| 481 | git config git-p4.branchList main:branchA |
| 482 | git config --add git-p4.branchList main:branchB |
| 483 | ------------- |
| 484 | |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 485 | git-p4.ignoredP4Labels:: |
| 486 | List of p4 labels to ignore. This is built automatically as |
| 487 | unimportable labels are discovered. |
| 488 | |
| 489 | git-p4.importLabels:: |
| 490 | Import p4 labels into git, as per --import-labels. |
| 491 | |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 492 | git-p4.labelImportRegexp:: |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 493 | Only p4 labels matching this regular expression will be imported. The |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 494 | default value is '[a-zA-Z0-9_\-.]+$'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 495 | |
| 496 | git-p4.useClientSpec:: |
Pete Wyckoff | 896a681 | 2012-01-02 18:05:54 -0500 | [diff] [blame] | 497 | Specify that the p4 client spec should be used to identify p4 |
| 498 | depot paths of interest. This is equivalent to specifying the |
| 499 | option '--use-client-spec'. See the "CLIENT SPEC" section above. |
| 500 | This variable is a boolean, not the name of a p4 client. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 501 | |
| 502 | Submit variables |
| 503 | ~~~~~~~~~~~~~~~~ |
| 504 | git-p4.detectRenames:: |
Gary Gibbons | 84cb000 | 2012-07-04 09:40:19 -0400 | [diff] [blame] | 505 | Detect renames. See linkgit:git-diff[1]. This can be true, |
| 506 | false, or a score as expected by 'git diff -M'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 507 | |
| 508 | git-p4.detectCopies:: |
Gary Gibbons | 84cb000 | 2012-07-04 09:40:19 -0400 | [diff] [blame] | 509 | Detect copies. See linkgit:git-diff[1]. This can be true, |
| 510 | false, or a score as expected by 'git diff -C'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 511 | |
| 512 | git-p4.detectCopiesHarder:: |
Gary Gibbons | 84cb000 | 2012-07-04 09:40:19 -0400 | [diff] [blame] | 513 | Detect copies harder. See linkgit:git-diff[1]. A boolean. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 514 | |
| 515 | git-p4.preserveUser:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 516 | On submit, re-author changes to reflect the Git author, |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 517 | regardless of who invokes 'git p4 submit'. |
| 518 | |
| 519 | git-p4.allowMissingP4Users:: |
| 520 | When 'preserveUser' is true, 'git p4' normally dies if it |
| 521 | cannot find an author in the p4 user map. This setting |
| 522 | submits the change regardless. |
| 523 | |
| 524 | git-p4.skipSubmitEdit:: |
| 525 | The submit process invokes the editor before each p4 change |
| 526 | is submitted. If this setting is true, though, the editing |
| 527 | step is skipped. |
| 528 | |
| 529 | git-p4.skipSubmitEditCheck:: |
| 530 | After editing the p4 change message, 'git p4' makes sure that |
| 531 | the description really was changed by looking at the file |
| 532 | modification time. This option disables that test. |
| 533 | |
| 534 | git-p4.allowSubmit:: |
| 535 | By default, any branch can be used as the source for a 'git p4 |
| 536 | submit' operation. This configuration variable, if set, permits only |
Pete Wyckoff | 28755db | 2011-12-24 21:07:40 -0500 | [diff] [blame] | 537 | the named branches to be used as submit sources. Branch names |
| 538 | must be the short names (no "refs/heads/"), and should be |
| 539 | separated by commas (","), with no spaces. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 540 | |
| 541 | git-p4.skipUserNameCheck:: |
| 542 | If the user running 'git p4 submit' does not exist in the p4 |
| 543 | user map, 'git p4' exits. This option can be used to force |
| 544 | submission regardless. |
| 545 | |
Pete Wyckoff | 41925d5 | 2012-05-06 11:58:38 -0400 | [diff] [blame] | 546 | git-p4.attemptRCSCleanup:: |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 547 | If enabled, 'git p4 submit' will attempt to cleanup RCS keywords |
| 548 | ($Header$, etc). These would otherwise cause merge conflicts and prevent |
| 549 | the submit going ahead. This option should be considered experimental at |
| 550 | present. |
| 551 | |
| 552 | git-p4.exportLabels:: |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 553 | Export Git tags to p4 labels, as per --export-labels. |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 554 | |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 555 | git-p4.labelExportRegexp:: |
Luke Diamand | 06804c7 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 556 | Only p4 labels matching this regular expression will be exported. The |
Luke Diamand | c8942a2 | 2012-04-11 17:21:24 +0200 | [diff] [blame] | 557 | default value is '[a-zA-Z0-9_\-.]+$'. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 558 | |
Pete Wyckoff | 6bbfd13 | 2012-09-09 16:16:13 -0400 | [diff] [blame] | 559 | git-p4.conflict:: |
| 560 | Specify submit behavior when a conflict with p4 is found, as per |
| 561 | --conflict. The default behavior is 'ask'. |
| 562 | |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 563 | IMPLEMENTATION DETAILS |
| 564 | ---------------------- |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 565 | * Changesets from p4 are imported using Git fast-import. |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 566 | * Cloning or syncing does not require a p4 client; file contents are |
| 567 | collected using 'p4 print'. |
| 568 | * Submitting requires a p4 client, which is not in the same location |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 569 | as the Git repository. Patches are applied, one at a time, to |
Pete Wyckoff | 6679c34 | 2011-12-24 21:07:31 -0500 | [diff] [blame] | 570 | this p4 client and submitted from there. |
| 571 | * Each commit imported by 'git p4' has a line at the end of the log |
| 572 | message indicating the p4 depot location and change number. This |
| 573 | line is used by later 'git p4 sync' operations to know which p4 |
| 574 | changes are new. |