Initial bulk commit for "Git on MSys"
[msysgit/historical-msysgit.git] / git / contrib / p4import / git-p4import.txt
blob9967587fe6bef0cf7cc3e93467bd179f6f58b032
1 git-p4import(1)
2 ===============
4 NAME
5 ----
6 git-p4import - Import a Perforce repository into git
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`
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.
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.
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).
34 OPTIONS
35 -------
36 -q::
37         Do not display any progress information.
39 -v::
40         Give extra progress information.
42 \--authors::
43         Specify an authors file containing a mapping of Perforce user
44         ids to full names and email addresses (see Notes below).
46 \--notags::
47         Do not create a tag for each imported commit.
49 \--stitch::
50         Import the contents of the given perforce branch into the
51         currently checked out git branch.
53 \--log::
54         Store debugging information in the specified file.
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.
62 <//p4repo/path>::
63         The Perforce path that will be imported into the specified branch.
65 <branch>::
66         The new branch that will be created to hold the Perforce imports.
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.
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:
79 ------------
80 Client: myhost
82 Root:   /home/sean/import
84 Options:   noallwrite clobber nocompress unlocked modtime rmdir
86 View:
87         //public/jam/... //myhost/jam/...
88 ------------
90 With the above `p4` client setup, you could import the "jam"
91 perforce branch into a branch named "jammy", like so:
93 ------------
94 $ mkdir -p /home/sean/import/jam
95 $ cd /home/sean/import/jam
96 $ git init
97 $ git p4import //public/jam jammy
98 ------------
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:
109 ------------
110 View:
111         //public/jam/... //myhost/jam/...
112         //public/other/... //myhost/jam/...
113         //public/guest/... //myhost/jam/...
114 ------------
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.
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.
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.
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.
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.
144 Notes
145 -----
146 You can interrupt the import (e.g. ctrl-c) at any time and restart it
147 without worry.
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:
155 ------------
156     perforce_id = Full Name <email@address.com>
157 ------------
160 Author
161 ------
162 Written by Sean Estabrooks <seanlkml@sympatico.ca>
167 Part of the gitlink:git[7] suite