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