You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
531 lines
17 KiB
531 lines
17 KiB
git-p4(1) |
|
========= |
|
|
|
NAME |
|
---- |
|
git-p4 - Import from and submit to Perforce repositories |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... |
|
'git p4 sync' [<sync options>] [<p4 depot path>...] |
|
'git p4 rebase' |
|
'git p4 submit' [<submit options>] [<master branch name>] |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
This command provides a way to interact with p4 repositories |
|
using git. |
|
|
|
Create a new git repository from an existing p4 repository using |
|
'git p4 clone', giving it one or more p4 depot paths. Incorporate |
|
new commits from p4 changes with 'git p4 sync'. The 'sync' command |
|
is also used to include new branches from other p4 depot paths. |
|
Submit git changes back to p4 using 'git p4 submit'. The command |
|
'git p4 rebase' does a sync plus rebases the current branch onto |
|
the updated p4 remote branch. |
|
|
|
|
|
EXAMPLE |
|
------- |
|
* Clone a repository: |
|
+ |
|
------------ |
|
$ git p4 clone //depot/path/project |
|
------------ |
|
|
|
* Do some work in the newly created git repository: |
|
+ |
|
------------ |
|
$ cd project |
|
$ vi foo.h |
|
$ git commit -a -m "edited foo.h" |
|
------------ |
|
|
|
* Update the git repository with recent changes from p4, rebasing your |
|
work on top: |
|
+ |
|
------------ |
|
$ git p4 rebase |
|
------------ |
|
|
|
* Submit your commits back to p4: |
|
+ |
|
------------ |
|
$ git p4 submit |
|
------------ |
|
|
|
|
|
COMMANDS |
|
-------- |
|
|
|
Clone |
|
~~~~~ |
|
Generally, 'git p4 clone' is used to create a new git directory |
|
from an existing p4 repository: |
|
------------ |
|
$ git p4 clone //depot/path/project |
|
------------ |
|
This: |
|
|
|
1. Creates an empty git repository in a subdirectory called 'project'. |
|
+ |
|
2. Imports the full contents of the head revision from the given p4 |
|
depot path into a single commit in the git branch 'refs/remotes/p4/master'. |
|
+ |
|
3. Creates a local branch, 'master' from this remote and checks it out. |
|
|
|
To reproduce the entire p4 history in git, use the '@all' modifier on |
|
the depot path: |
|
------------ |
|
$ git p4 clone //depot/path/project@all |
|
------------ |
|
|
|
|
|
Sync |
|
~~~~ |
|
As development continues in the p4 repository, those changes can |
|
be included in the git repository using: |
|
------------ |
|
$ git p4 sync |
|
------------ |
|
This command finds new changes in p4 and imports them as git commits. |
|
|
|
P4 repositories can be added to an existing git repository using |
|
'git p4 sync' too: |
|
------------ |
|
$ mkdir repo-git |
|
$ cd repo-git |
|
$ git init |
|
$ git p4 sync //path/in/your/perforce/depot |
|
------------ |
|
This imports the specified depot into |
|
'refs/remotes/p4/master' in an existing git repository. The |
|
'--branch' option can be used to specify a different branch to |
|
be used for the p4 content. |
|
|
|
If a git repository includes branches 'refs/remotes/origin/p4', these |
|
will be fetched and consulted first during a 'git p4 sync'. Since |
|
importing directly from p4 is considerably slower than pulling changes |
|
from a git remote, this can be useful in a multi-developer environment. |
|
|
|
|
|
Rebase |
|
~~~~~~ |
|
A common working pattern is to fetch the latest changes from the p4 depot |
|
and merge them with local uncommitted changes. Often, the p4 repository |
|
is the ultimate location for all code, thus a rebase workflow makes |
|
sense. This command does 'git p4 sync' followed by 'git rebase' to move |
|
local commits on top of updated p4 changes. |
|
------------ |
|
$ git p4 rebase |
|
------------ |
|
|
|
|
|
Submit |
|
~~~~~~ |
|
Submitting changes from a git repository back to the p4 repository |
|
requires a separate p4 client workspace. This should be specified |
|
using the 'P4CLIENT' environment variable or the git configuration |
|
variable 'git-p4.client'. The p4 client must exist, but the client root |
|
will be created and populated if it does not already exist. |
|
|
|
To submit all changes that are in the current git branch but not in |
|
the 'p4/master' branch, use: |
|
------------ |
|
$ git p4 submit |
|
------------ |
|
|
|
To specify a branch other than the current one, use: |
|
------------ |
|
$ git p4 submit topicbranch |
|
------------ |
|
|
|
The upstream reference is generally 'refs/remotes/p4/master', but can |
|
be overridden using the '--origin=' command-line option. |
|
|
|
The p4 changes will be created as the user invoking 'git p4 submit'. The |
|
'--preserve-user' option will cause ownership to be modified |
|
according to the author of the git commit. This option requires admin |
|
privileges in p4, which can be granted using 'p4 protect'. |
|
|
|
|
|
OPTIONS |
|
------- |
|
|
|
General options |
|
~~~~~~~~~~~~~~~ |
|
All commands except clone accept these options. |
|
|
|
--git-dir <dir>:: |
|
Set the 'GIT_DIR' environment variable. See linkgit:git[1]. |
|
|
|
--verbose:: |
|
Provide more progress information. |
|
|
|
Sync options |
|
~~~~~~~~~~~~ |
|
These options can be used in the initial 'clone' as well as in |
|
subsequent 'sync' operations. |
|
|
|
--branch <branch>:: |
|
Import changes into given branch. If the branch starts with |
|
'refs/', it will be used as is, otherwise the path 'refs/heads/' |
|
will be prepended. The default branch is 'master'. If used |
|
with an initial clone, no HEAD will be checked out. |
|
+ |
|
This example imports a new remote "p4/proj2" into an existing |
|
git repository: |
|
+ |
|
---- |
|
$ git init |
|
$ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 |
|
---- |
|
|
|
--detect-branches:: |
|
Use the branch detection algorithm to find new paths in p4. It is |
|
documented below in "BRANCH DETECTION". |
|
|
|
--changesfile <file>:: |
|
Import exactly the p4 change numbers listed in 'file', one per |
|
line. Normally, 'git p4' inspects the current p4 repository |
|
state and detects the changes it should import. |
|
|
|
--silent:: |
|
Do not print any progress information. |
|
|
|
--detect-labels:: |
|
Query p4 for labels associated with the depot paths, and add |
|
them as tags in git. Limited usefulness as only imports labels |
|
associated with new changelists. Deprecated. |
|
|
|
--import-labels:: |
|
Import labels from p4 into git. |
|
|
|
--import-local:: |
|
By default, p4 branches are stored in 'refs/remotes/p4/', |
|
where they will be treated as remote-tracking branches by |
|
linkgit:git-branch[1] and other commands. This option instead |
|
puts p4 branches in 'refs/heads/p4/'. Note that future |
|
sync operations must specify '--import-local' as well so that |
|
they can find the p4 branches in refs/heads. |
|
|
|
--max-changes <n>:: |
|
Limit the number of imported changes to 'n'. Useful to |
|
limit the amount of history when using the '@all' p4 revision |
|
specifier. |
|
|
|
--keep-path:: |
|
The mapping of file names from the p4 depot path to git, by |
|
default, involves removing the entire depot path. With this |
|
option, the full p4 depot path is retained in git. For example, |
|
path '//depot/main/foo/bar.c', when imported from |
|
'//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the |
|
git path is instead 'depot/main/foo/bar.c'. |
|
|
|
--use-client-spec:: |
|
Use a client spec to find the list of interesting files in p4. |
|
See the "CLIENT SPEC" section below. |
|
|
|
Clone options |
|
~~~~~~~~~~~~~ |
|
These options can be used in an initial 'clone', along with the 'sync' |
|
options described above. |
|
|
|
--destination <directory>:: |
|
Where to create the git repository. If not provided, the last |
|
component in the p4 depot path is used to create a new |
|
directory. |
|
|
|
--bare:: |
|
Perform a bare clone. See linkgit:git-clone[1]. |
|
|
|
-/ <path>:: |
|
Exclude selected depot paths when cloning. |
|
|
|
Submit options |
|
~~~~~~~~~~~~~~ |
|
These options can be used to modify 'git p4 submit' behavior. |
|
|
|
--origin <commit>:: |
|
Upstream location from which commits are identified to submit to |
|
p4. By default, this is the most recent p4 commit reachable |
|
from 'HEAD'. |
|
|
|
-M[<n>]:: |
|
Detect renames. See linkgit:git-diff[1]. Renames will be |
|
represented in p4 using explicit 'move' operations. There |
|
is no corresponding option to detect copies, but there are |
|
variables for both moves and copies. |
|
|
|
--preserve-user:: |
|
Re-author p4 changes before submitting to p4. This option |
|
requires p4 admin privileges. |
|
|
|
--export-labels:: |
|
Export tags from git as p4 labels. Tags found in git are applied |
|
to the perforce working directory. |
|
|
|
Rebase options |
|
~~~~~~~~~~~~~~ |
|
These options can be used to modify 'git p4 rebase' behavior. |
|
|
|
--import-labels:: |
|
Import p4 labels. |
|
|
|
DEPOT PATH SYNTAX |
|
----------------- |
|
The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can |
|
be one or more space-separated p4 depot paths, with an optional |
|
p4 revision specifier on the end: |
|
|
|
"//depot/my/project":: |
|
Import one commit with all files in the '#head' change under that tree. |
|
|
|
"//depot/my/project@all":: |
|
Import one commit for each change in the history of that depot path. |
|
|
|
"//depot/my/project@1,6":: |
|
Import only changes 1 through 6. |
|
|
|
"//depot/proj1@all //depot/proj2@all":: |
|
Import all changes from both named depot paths into a single |
|
repository. Only files below these directories are included. |
|
There is not a subdirectory in git for each "proj1" and "proj2". |
|
You must use the '--destination' option when specifying more |
|
than one depot path. The revision specifier must be specified |
|
identically on each depot path. If there are files in the |
|
depot paths with the same name, the path with the most recently |
|
updated version of the file is the one that appears in git. |
|
|
|
See 'p4 help revisions' for the full syntax of p4 revision specifiers. |
|
|
|
|
|
CLIENT SPEC |
|
----------- |
|
The p4 client specification is maintained with the 'p4 client' command |
|
and contains among other fields, a View that specifies how the depot |
|
is mapped into the client repository. The 'clone' and 'sync' commands |
|
can consult the client spec when given the '--use-client-spec' option or |
|
when the useClientSpec variable is true. After 'git p4 clone', the |
|
useClientSpec variable is automatically set in the repository |
|
configuration file. This allows future 'git p4 submit' commands to |
|
work properly; the submit command looks only at the variable and does |
|
not have a command-line option. |
|
|
|
The full syntax for a p4 view is documented in 'p4 help views'. 'Git p4' |
|
knows only a subset of the view syntax. It understands multi-line |
|
mappings, overlays with '+', exclusions with '-' and double-quotes |
|
around whitespace. Of the possible wildcards, 'git p4' only handles |
|
'...', and only when it is at the end of the path. 'Git p4' will complain |
|
if it encounters an unhandled wildcard. |
|
|
|
Bugs in the implementation of overlap mappings exist. If multiple depot |
|
paths map through overlays to the same location in the repository, |
|
'git p4' can choose the wrong one. This is hard to solve without |
|
dedicating a client spec just for 'git p4'. |
|
|
|
The name of the client can be given to 'git p4' in multiple ways. The |
|
variable 'git-p4.client' takes precedence if it exists. Otherwise, |
|
normal p4 mechanisms of determining the client are used: environment |
|
variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. |
|
|
|
|
|
BRANCH DETECTION |
|
---------------- |
|
P4 does not have the same concept of a branch as git. Instead, |
|
p4 organizes its content as a directory tree, where by convention |
|
different logical branches are in different locations in the tree. |
|
The 'p4 branch' command is used to maintain mappings between |
|
different areas in the tree, and indicate related content. 'git p4' |
|
can use these mappings to determine branch relationships. |
|
|
|
If you have a repository where all the branches of interest exist as |
|
subdirectories of a single depot path, you can use '--detect-branches' |
|
when cloning or syncing to have 'git p4' automatically find |
|
subdirectories in p4, and to generate these as branches in git. |
|
|
|
For example, if the P4 repository structure is: |
|
---- |
|
//depot/main/... |
|
//depot/branch1/... |
|
---- |
|
|
|
And "p4 branch -o branch1" shows a View line that looks like: |
|
---- |
|
//depot/main/... //depot/branch1/... |
|
---- |
|
|
|
Then this 'git p4 clone' command: |
|
---- |
|
git p4 clone --detect-branches //depot@all |
|
---- |
|
produces a separate branch in 'refs/remotes/p4/' for //depot/main, |
|
called 'master', and one for //depot/branch1 called 'depot/branch1'. |
|
|
|
However, it is not necessary to create branches in p4 to be able to use |
|
them like branches. Because it is difficult to infer branch |
|
relationships automatically, a git configuration setting |
|
'git-p4.branchList' can be used to explicitly identify branch |
|
relationships. It is a list of "source:destination" pairs, like a |
|
simple p4 branch specification, where the "source" and "destination" are |
|
the path elements in the p4 repository. The example above relied on the |
|
presence of the p4 branch. Without p4 branches, the same result will |
|
occur with: |
|
---- |
|
git config git-p4.branchList main:branch1 |
|
git p4 clone --detect-branches //depot@all |
|
---- |
|
|
|
|
|
PERFORMANCE |
|
----------- |
|
The fast-import mechanism used by 'git p4' creates one pack file for |
|
each invocation of 'git p4 sync'. Normally, git garbage compression |
|
(linkgit:git-gc[1]) automatically compresses these to fewer pack files, |
|
but explicit invocation of 'git repack -adf' may improve performance. |
|
|
|
|
|
CONFIGURATION VARIABLES |
|
----------------------- |
|
The following config settings can be used to modify 'git p4' behavior. |
|
They all are in the 'git-p4' section. |
|
|
|
General variables |
|
~~~~~~~~~~~~~~~~~ |
|
git-p4.user:: |
|
User specified as an option to all p4 commands, with '-u <user>'. |
|
The environment variable 'P4USER' can be used instead. |
|
|
|
git-p4.password:: |
|
Password specified as an option to all p4 commands, with |
|
'-P <password>'. |
|
The environment variable 'P4PASS' can be used instead. |
|
|
|
git-p4.port:: |
|
Port specified as an option to all p4 commands, with |
|
'-p <port>'. |
|
The environment variable 'P4PORT' can be used instead. |
|
|
|
git-p4.host:: |
|
Host specified as an option to all p4 commands, with |
|
'-h <host>'. |
|
The environment variable 'P4HOST' can be used instead. |
|
|
|
git-p4.client:: |
|
Client specified as an option to all p4 commands, with |
|
'-c <client>', including the client spec. |
|
|
|
Clone and sync variables |
|
~~~~~~~~~~~~~~~~~~~~~~~~ |
|
git-p4.syncFromOrigin:: |
|
Because importing commits from other git repositories is much faster |
|
than importing them from p4, a mechanism exists to find p4 changes |
|
first in git remotes. If branches exist under 'refs/remote/origin/p4', |
|
those will be fetched and used when syncing from p4. This |
|
variable can be set to 'false' to disable this behavior. |
|
|
|
git-p4.branchUser:: |
|
One phase in branch detection involves looking at p4 branches |
|
to find new ones to import. By default, all branches are |
|
inspected. This option limits the search to just those owned |
|
by the single user named in the variable. |
|
|
|
git-p4.branchList:: |
|
List of branches to be imported when branch detection is |
|
enabled. Each entry should be a pair of branch names separated |
|
by a colon (:). This example declares that both branchA and |
|
branchB were created from main: |
|
+ |
|
------------- |
|
git config git-p4.branchList main:branchA |
|
git config --add git-p4.branchList main:branchB |
|
------------- |
|
|
|
git-p4.ignoredP4Labels:: |
|
List of p4 labels to ignore. This is built automatically as |
|
unimportable labels are discovered. |
|
|
|
git-p4.importLabels:: |
|
Import p4 labels into git, as per --import-labels. |
|
|
|
git-p4.labelImportRegexp:: |
|
Only p4 labels matching this regular expression will be imported. The |
|
default value is '[a-zA-Z0-9_\-.]+$'. |
|
|
|
git-p4.useClientSpec:: |
|
Specify that the p4 client spec should be used to identify p4 |
|
depot paths of interest. This is equivalent to specifying the |
|
option '--use-client-spec'. See the "CLIENT SPEC" section above. |
|
This variable is a boolean, not the name of a p4 client. |
|
|
|
Submit variables |
|
~~~~~~~~~~~~~~~~ |
|
git-p4.detectRenames:: |
|
Detect renames. See linkgit:git-diff[1]. |
|
|
|
git-p4.detectCopies:: |
|
Detect copies. See linkgit:git-diff[1]. |
|
|
|
git-p4.detectCopiesHarder:: |
|
Detect copies harder. See linkgit:git-diff[1]. |
|
|
|
git-p4.preserveUser:: |
|
On submit, re-author changes to reflect the git author, |
|
regardless of who invokes 'git p4 submit'. |
|
|
|
git-p4.allowMissingP4Users:: |
|
When 'preserveUser' is true, 'git p4' normally dies if it |
|
cannot find an author in the p4 user map. This setting |
|
submits the change regardless. |
|
|
|
git-p4.skipSubmitEdit:: |
|
The submit process invokes the editor before each p4 change |
|
is submitted. If this setting is true, though, the editing |
|
step is skipped. |
|
|
|
git-p4.skipSubmitEditCheck:: |
|
After editing the p4 change message, 'git p4' makes sure that |
|
the description really was changed by looking at the file |
|
modification time. This option disables that test. |
|
|
|
git-p4.allowSubmit:: |
|
By default, any branch can be used as the source for a 'git p4 |
|
submit' operation. This configuration variable, if set, permits only |
|
the named branches to be used as submit sources. Branch names |
|
must be the short names (no "refs/heads/"), and should be |
|
separated by commas (","), with no spaces. |
|
|
|
git-p4.skipUserNameCheck:: |
|
If the user running 'git p4 submit' does not exist in the p4 |
|
user map, 'git p4' exits. This option can be used to force |
|
submission regardless. |
|
|
|
git-p4.attemptRCSCleanup:: |
|
If enabled, 'git p4 submit' will attempt to cleanup RCS keywords |
|
($Header$, etc). These would otherwise cause merge conflicts and prevent |
|
the submit going ahead. This option should be considered experimental at |
|
present. |
|
|
|
git-p4.exportLabels:: |
|
Export git tags to p4 labels, as per --export-labels. |
|
|
|
git-p4.labelExportRegexp:: |
|
Only p4 labels matching this regular expression will be exported. The |
|
default value is '[a-zA-Z0-9_\-.]+$'. |
|
|
|
IMPLEMENTATION DETAILS |
|
---------------------- |
|
* Changesets from p4 are imported using git fast-import. |
|
* Cloning or syncing does not require a p4 client; file contents are |
|
collected using 'p4 print'. |
|
* Submitting requires a p4 client, which is not in the same location |
|
as the git repository. Patches are applied, one at a time, to |
|
this p4 client and submitted from there. |
|
* Each commit imported by 'git p4' has a line at the end of the log |
|
message indicating the p4 depot location and change number. This |
|
line is used by later 'git p4 sync' operations to know which p4 |
|
changes are new.
|
|
|