contrib/fast-import/git-p4.txt

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