EXAMPLE
-------
-* Create an alias for 'git p4', using the full path to the 'git-p4'
- script if needed:
-+
-------------
-$ git config --global alias.p4 '!git-p4'
-------------
-
* Clone a repository:
+
------------
General options
~~~~~~~~~~~~~~~
-All commands except clone accept this option.
+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
--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'.
+ 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
--silent::
Do not print any progress information.
---verbose::
- Provide more progress information.
-
--detect-labels::
Query p4 for labels associated with the depot paths, and add
- them as tags in git.
+ 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/'.
+ 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
--use-client-spec::
Use a client spec to find the list of interesting files in p4.
- The client spec is discovered using 'p4 client -o' which checks
- the 'P4CLIENT' environment variable and returns a mapping of
- depot files to workspace files.
+ See the "CLIENT SPEC" section below.
Clone options
~~~~~~~~~~~~~
~~~~~~~~~~~~~~
These options can be used to modify 'git p4 submit' behavior.
---verbose::
- Provide more progress information.
-
--origin <commit>::
Upstream location from which commits are identified to submit to
p4. By default, this is the most recent p4 commit reachable
-M[<n>]::
Detect renames. See linkgit:git-diff[1]. Renames will be
- represented in p4 using explicit 'move' operations.
+ 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
-----------------
"//depot/my/project@1,6"::
Import only changes 1 through 6.
-"//depot/proj1 //depot/proj2@all"::
- Import all changes from both named depot paths.
+"//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,
git-p4.client::
Client specified as an option to all p4 commands, with
- '-c <client>'. This can also be used as a way to find
- the client spec for the 'useClientSpec' option.
- The environment variable 'P4CLIENT' can be used instead.
+ '-c <client>', including the client spec.
Clone and sync variables
~~~~~~~~~~~~~~~~~~~~~~~~
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 to be used to identify p4 depot
- paths of interest. This is equivalent to specifying the option
- '--use-client-spec'. The variable 'git-p4.client' can be used
- to specify the name of the client.
+ 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.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.
+ 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
----------------------