Documentation/git-p4import.txt

   1 git-p4import(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-p4import - Import a Perforce repository into git
   7
   8
   9 SYNOPSIS
  10 --------
  11 `git-p4import` [-q|-v] [--authors <file>] [-t <timezone>] <//p4repo/path> <branch>
  12
  13 `git-p4import` --stitch <//p4repo/path>
  14
  15 `git-p4import`
  16
  17
  18 DESCRIPTION
  19 -----------
  20 Import a Perforce repository into an existing git repository.  When
  21 a <//p4repo/path> and <branch> are specified a new branch with the
  22 given name will be created and the initial import will begin.
  23
  24 Once the initial import is complete you can do an incremental import
  25 of new commits from the Perforce repository.  You do this by checking
  26 out the appropriate git branch and then running `git-p4import` without
  27 any options.
  28
  29 The standard p4 client is used to communicate with the Perforce
  30 repository; it must be configured correctly in order for `git-p4import`
  31 to operate (see below).
  32
  33
  34 OPTIONS
  35 -------
  36 -q::
  37         Do not display any progress information.
  38
  39 -v::
  40         Give extra progress information.
  41
  42 \--authors::
  43         Specify an authors file containing a mapping of Perforce user
  44         ids to full names and email addresses (see Notes below).
  45
  46 \--stitch::
  47         Import the contents of the given perforce branch into the
  48         currently checked out git branch.
  49
  50 \--log::
  51         Store debugging information in the specified file.
  52
  53 -t::
  54         Specify that the remote repository is in the specified timezone.
  55         Timezone must be in the format "US/Pacific" or "Europe/London"
  56         etc.  You only need to specify this once, it will be saved in
  57         the git config file for the repository.
  58
  59 <//p4repo/path>::
  60         The Perforce path that will be imported into the specified branch.
  61
  62 <branch>::
  63         The new branch that will be created to hold the Perforce imports.
  64
  65
  66 P4 Client
  67 ---------
  68 You must make the `p4` client command available in your $PATH and
  69 configure it to communicate with the target Perforce repository.
  70 Typically this means you must set the "$P4PORT" and "$P4CLIENT"
  71 environment variables.
  72
  73 You must also configure a `p4` client "view" which maps the Perforce
  74 branch into the top level of your git repository, for example:
  75
  76 ------------
  77 Client: myhost
  78
  79 Root:   /home/sean/import
  80
  81 Options:   noallwrite clobber nocompress unlocked modtime rmdir
  82
  83 View:
  84         //public/jam/... //myhost/jam/...
  85 ------------
  86
  87 With the above `p4` client setup, you could import the "jam"
  88 perforce branch into a branch named "jammy", like so:
  89
  90 ------------
  91 $ mkdir -p /home/sean/import/jam
  92 $ cd /home/sean/import/jam
  93 $ git init-db
  94 $ git p4import //public/jam jammy
  95 ------------
  96
  97
  98 Multiple Branches
  99 -----------------
 100 Note that by creating multiple "views" you can use `git-p4import`
 101 to import additional branches into the same git repository.
 102 However, the `p4` client has a limitation in that it silently
 103 ignores all but the last "view" that maps into the same local
 104 directory.  So the following will *not* work:
 105
 106 ------------
 107 View:
 108         //public/jam/... //myhost/jam/...
 109         //public/other/... //myhost/jam/...
 110         //public/guest/... //myhost/jam/...
 111 ------------
 112
 113 If you want more than one Perforce branch to be imported into the
 114 same directory you must employ a workaround.  A simple option is
 115 to adjust your `p4` client before each import to only include a
 116 single view.
 117
 118 Another option is to create multiple symlinks locally which all
 119 point to the same directory in your git repository and then use
 120 one per "view" instead of listing the actual directory.
 121
 122
 123 Tags
 124 ----
 125 A git tag of the form p4/xx is created for every change imported from
 126 the Perforce repository where xx is the Perforce changeset number.
 127 Therefore after the import you can use git to access any commit by its
 128 Perforce number, eg. git show p4/327.
 129
 130 The tag associated with the HEAD commit is also how `git-p4import`
 131 determines if their are new changes to incrementally import from the
 132 Perforce repository.
 133
 134 If you import from a repository with many thousands of changes
 135 you will have an equal number of p4/xxxx git tags.  Git tags can
 136 be expensive in terms of disk space and repository operations.
 137 If you don't need to perform further incremental imports, you
 138 may delete the tags.
 139
 140
 141 Notes
 142 -----
 143 You can interrupt the import (eg. ctrl-c) at any time and restart it
 144 without worry.
 145
 146 Author information is automatically determined by querying the
 147 Perforce "users" table using the id associated with each change.
 148 However, if you want to manually supply these mappings you can do
 149 so with the "--authors" option.  It accepts a file containing a list
 150 of mappings with each line containing one mapping in the format:
 151
 152 ------------
 153     perforce_id = Full Name <email@address.com>
 154 ------------
 155
 156
 157 Author
 158 ------
 159 Written by Sean Estabrooks <seanlkml@sympatico.ca>
 160
 161
 162 GIT
 163 ---
 164 Part of the gitlink:git[7] suite
 165