path: root/Documentation/git-p4.txt

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.


EXAMPLES
--------
* 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.

If there are multiple branches, doing 'git p4 sync' will automatically
use the "BRANCH DETECTION" algorithm to try to partition new changes
into the right branch.  This can be overridden with the `--branch`
option to specify just a single branch to update.


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
------------

To specify a single commit or a range of commits, use:
------------
$ git p4 submit --commit <sha1>
$ git p4 submit --commit <sha1..sha1>
------------

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'.

To shelve changes instead of submitting, use `--shelve` and `--update-shelve`:

----
$ git p4 submit --shelve
$ git p4 submit --update-shelve 1234 --update-shelve 2345
----


Unshelve
~~~~~~~~
Unshelving will take a shelved P4 changelist, and produce the equivalent git commit
in the branch refs/remotes/p4-unshelved/<changelist>.

The git commit is created relative to the current origin revision (HEAD by default).
A parent commit is created based on the origin, and then the unshelve commit is
created based on that.

The origin revision can be changed with the "--origin" option.

If the target branch in refs/remotes/p4-unshelved already exists, the old one will
be renamed.

----
$ git p4 sync
$ git p4 unshelve 12345
$ git show p4-unshelved/12345
<submit more changes via p4 to the same files>
$ git p4 unshelve 12345
<refuses to unshelve until git is in sync with p4 again>

----

OPTIONS
-------

General options
~~~~~~~~~~~~~~~
All commands except clone accept these options.

--git-dir <dir>::
	Set the `GIT_DIR` environment variable.  See linkgit:git[1].

-v::
--verbose::
	Provide more progress information.

Sync options
~~~~~~~~~~~~
These options can be used in the initial 'clone' as well as in
subsequent 'sync' operations.

--branch <ref>::
	Import changes into <ref> instead of refs/remotes/p4/master.
	If <ref> starts with refs/, it is used as is.  Otherwise, if
	it does not start with p4/, that prefix is added.
+
By default a <ref> not starting with refs/ is treated as the
name of a remote-tracking branch (under refs/remotes/).  This
behavior can be modified using the --import-local option.
+
The default <ref> is "master".
+
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>::
	Import at most 'n' changes, rather than the entire range of
	changes included in the given revision specifier. A typical
	usage would be use '@all' as the revision specifier, but then
	to use '--max-changes 1000' to import only the last 1000
	revisions rather than the entire revision history.

--changes-block-size <n>::
	The internal block size to use when converting a revision
	specifier such as '@all' into a list of specific change
	numbers. Instead of using a single call to 'p4 changes' to
	find the full list of changes for the conversion, there are a
	sequence of calls to 'p4 changes -m', each of which requests
	one block of changes of the given size. The default block size
	is 500, which should usually be suitable.

--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.

-/ <path>::
	Exclude selected depot paths when cloning or syncing.

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].

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::
	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.

-n::
--dry-run::
	Show just what commits would be submitted to p4; do not change
	state in Git or p4.

--prepare-p4-only::
	Apply a commit to the p4 workspace, opening, adding and deleting
	files in p4 as for a normal submit operation.  Do not issue the
	final "p4 submit", but instead print a message about how to
	submit manually or revert.  This option always stops after the
	first (oldest) commit.  Git tags are not exported to p4.

--shelve::
	Instead of submitting create a series of shelved changelists.
	After creating each shelve, the relevant files are reverted/deleted.
	If you have multiple commits pending multiple shelves will be created.

--update-shelve CHANGELIST::
	Update an existing shelved changelist with this commit. Implies
	--shelve. Repeat for multiple shelved changelists.

--conflict=(ask|skip|quit)::
	Conflicts can occur when applying a commit to p4.  When this
	happens, the default behavior ("ask") is to prompt whether to
	skip this commit and continue, or quit.  This option can be used
	to bypass the prompt, causing conflicting commits to be automatically
	skipped, or to quit trying to apply commits, without prompting.

--branch <branch>::
	After submitting, sync this named branch instead of the default
	p4/master.  See the "Sync options" section above for more
	information.

--commit <sha1>|<sha1..sha1>::
    Submit only the specified commit or range of commits, instead of the full
    list of changes that are in the current Git branch.

--disable-rebase::
    Disable the automatic rebase after all commits have been successfully
    submitted. Can also be set with git-p4.disableRebase.

--disable-p4sync::
    Disable the automatic sync of p4/master from Perforce after commits have
    been submitted. Implies --disable-rebase. Can also be set with
    git-p4.disableP4Sync. Sync with origin/master still goes ahead if possible.

Hooks for submit
----------------

p4-pre-submit
~~~~~~~~~~~~~

The `p4-pre-submit` hook is executed if it exists and is executable.
The hook takes no parameters and nothing from standard input. Exiting with
non-zero status from this script prevents `git-p4 submit` from launching.
It can be bypassed with the `--no-verify` command line option.

One usage scenario is to run unit tests in the hook.

p4-prepare-changelist
~~~~~~~~~~~~~~~~~~~~~

The `p4-prepare-changelist` hook is executed right after preparing
the default changelist message and before the editor is started.
It takes one parameter, the name of the file that contains the
changelist text. Exiting with a non-zero status from the script
will abort the process.

The purpose of the hook is to edit the message file in place,
and it is not suppressed by the `--no-verify` option. This hook
is called even if `--prepare-p4-only` is set.

p4-changelist
~~~~~~~~~~~~~

The `p4-changelist` hook is executed after the changelist
message has been edited by the user. It can be bypassed with the
`--no-verify` option. It takes a single parameter, the name
of the file that holds the proposed changelist text. Exiting
with a non-zero status causes the command to abort.

The hook is allowed to edit the changelist file and can be used
to normalize the text into some project standard format. It can
also be used to refuse the Submit after inspect the message file.

p4-post-changelist
~~~~~~~~~~~~~~~~~~

The `p4-post-changelist` hook is invoked after the submit has
successfully occurred in P4. It takes no parameters and is meant
primarily for notification and cannot affect the outcome of the
git p4 submit action.



Rebase options
~~~~~~~~~~~~~~
These options can be used to modify 'git p4 rebase' behavior.

--import-labels::
	Import p4 labels.

Unshelve options
~~~~~~~~~~~~~~~~

--origin::
    Sets the git refspec against which the shelved P4 changelist is compared.
    Defaults to p4/master.

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