contrib/fast-import/git-p4.txt

   1 git-p4 - Perforce <-> Git converter using git-fast-import
   2
   3 Usage
   4 =====
   5
   6 git-p4 can be used in two different ways:
   7
   8 1) To import changes from Perforce to a Git repository, using "git-p4 sync".
   9
  10 2) To submit changes from Git back to Perforce, using "git-p4 submit".
  11
  12 Importing
  13 =========
  14
  15 Simply start with
  16
  17   git-p4 clone //depot/path/project
  18
  19 or
  20
  21   git-p4 clone //depot/path/project myproject
  22
  23 This will:
  24
  25 1) Create an empty git repository in a subdirectory called "project" (or
  26 "myproject" with the second command)
  27
  28 2) Import the head revision from the given Perforce path into a git branch
  29 called "p4" (remotes/p4 actually)
  30
  31 3) Create a master branch based on it and check it out.
  32
  33 If you want the entire history (not just the head revision) then you can simply
  34 append a "@all" to the depot path:
  35
  36   git-p4 clone //depot/project/main@all myproject
  37
  38
  39
  40 If you want more control you can also use the git-p4 sync command directly:
  41
  42   mkdir repo-git
  43   cd repo-git
  44   git init
  45   git-p4 sync //path/in/your/perforce/depot
  46
  47 This will import the current head revision of the specified depot path into a
  48 "remotes/p4/master" branch of your git repository. You can use the
  49 --branch=mybranch option to import into a different branch.
  50
  51 If you want to import the entire history of a given depot path simply use:
  52
  53   git-p4 sync //path/in/depot@all
  54
  55
  56 Note:
  57
  58 To achieve optimal compression you may want to run 'git repack -a -d -f' after
  59 a big import. This may take a while.
  60
  61 Incremental Imports
  62 ===================
  63
  64 After an initial import you can continue to synchronize your git repository
  65 with newer changes from the Perforce depot by just calling
  66
  67   git-p4 sync
  68
  69 in your git repository. By default the "remotes/p4/master" branch is updated.
  70
  71 Advanced Setup
  72 ==============
  73
  74 Suppose you have a periodically updated git repository somewhere, containing a
  75 complete import of a Perforce project. This repository can be cloned and used
  76 with git-p4. When updating the cloned repository with the "sync" command,
  77 git-p4 will try to fetch changes from the original repository first. The git
  78 protocol used with this is usually faster than importing from Perforce
  79 directly.
  80
  81 This behaviour can be disabled by setting the "git-p4.syncFromOrigin" git
  82 configuration variable to "false".
  83
  84 Updating
  85 ========
  86
  87 A common working pattern is to fetch the latest changes from the Perforce depot
  88 and merge them with local uncommitted changes. The recommended way is to use
  89 git's rebase mechanism to preserve linear history. git-p4 provides a convenient
  90
  91   git-p4 rebase
  92
  93 command that calls git-p4 sync followed by git rebase to rebase the current
  94 working branch.
  95
  96 Submitting
  97 ==========
  98
  99 git-p4 has support for submitting changes from a git repository back to the
 100 Perforce depot. This requires a Perforce checkout separate from your git
 101 repository. To submit all changes that are in the current git branch but not in
 102 the "p4" branch (or "origin" if "p4" doesn't exist) simply call
 103
 104     git-p4 submit
 105
 106 in your git repository. If you want to submit changes in a specific branch that
 107 is not your current git branch you can also pass that as an argument:
 108
 109     git-p4 submit mytopicbranch
 110
 111 You can override the reference branch with the --origin=mysourcebranch option.
 112
 113 If a submit fails you may have to "p4 resolve" and submit manually. You can
 114 continue importing the remaining changes with
 115
 116   git-p4 submit --continue
 117
 118 Example
 119 =======
 120
 121 # Clone a repository
 122   git-p4 clone //depot/path/project
 123 # Enter the newly cloned directory
 124   cd project
 125 # Do some work...
 126   vi foo.h
 127 # ... and commit locally to gi
 128   git commit foo.h
 129 # In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
 130 # changes against the latest changes in Perforce:
 131   git-p4 rebase
 132 # Submit your locally committed changes back to Perforce
 133   git-p4 submit
 134 # ... and synchronize with Perforce
 135   git-p4 rebase
 136
 137
 138 Configuration parameters
 139 ========================
 140
 141 git-p4.user ($P4USER)
 142
 143 Allows you to specify the username to use to connect to the Perforce repository.
 144
 145   git config [--global] git-p4.user public
 146
 147 git-p4.password ($P4PASS)
 148
 149 Allows you to specify the password to use to connect to the Perforce repository.
 150 Warning this password will be visible on the command-line invocation of the p4 binary.
 151
 152   git config [--global] git-p4.password public1234
 153
 154 git-p4.port ($P4PORT)
 155
 156 Specify the port to be used to contact the Perforce server. As this will be passed
 157 directly to the p4 binary, it may be in the format host:port as well.
 158
 159   git config [--global] git-p4.port codes.zimbra.com:2666
 160
 161 git-p4.host ($P4HOST)
 162
 163 Specify the host to contact for a Perforce repository.
 164
 165   git config [--global] git-p4.host perforce.example.com
 166
 167 git-p4.client ($P4CLIENT)
 168
 169 Specify the client name to use
 170
 171   git config [--global] git-p4.client public-view
 172
 173 git-p4.allowSubmit
 174
 175   git config [--global] git-p4.allowSubmit false
 176
 177 git-p4.syncFromOrigin
 178
 179 A useful setup may be that you have a periodically updated git repository
 180 somewhere that contains a complete import of a Perforce project. That git
 181 repository can be used to clone the working repository from and one would
 182 import from Perforce directly after cloning using git-p4. If the connection to
 183 the Perforce server is slow and the working repository hasn't been synced for a
 184 while it may be desirable to fetch changes from the origin git repository using
 185 the efficient git protocol. git-p4 supports this setup by calling "git fetch origin"
 186 by default if there is an origin branch. You can disable this using:
 187
 188   git config [--global] git-p4.syncFromOrigin false
 189
 190 git-p4.useclientspec
 191
 192   git config [--global] git-p4.useclientspec false
 193
 194 The P4CLIENT environment variable should be correctly set for p4 to be
 195 able to find the relevant client.  This client spec will be used to
 196 both filter the files cloned by git and set the directory layout as
 197 specified in the client (this implies --keep-path style semantics).
 198
 199 Implementation Details...
 200 =========================
 201
 202 * Changesets from Perforce are imported using git fast-import.
 203 * The import does not require anything from the Perforce client view as it just uses
 204   "p4 print //depot/path/file#revision" to get the actual file contents.
 205 * Every imported changeset has a special [git-p4...] line at the
 206   end of the log message that gives information about the corresponding
 207   Perforce change number and is also used by git-p4 itself to find out
 208   where to continue importing when doing incremental imports.
 209   Basically when syncing it extracts the perforce change number of the
 210   latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
 211   to find out which changes need to be imported.
 212 * git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
 213   and the current branch.
 214   The commits themselves are applied using git diff/format-patch ... | git apply
 215