Clean up the git-p4 documentation
This patch massages the documentation a bit for improved readability and cleans it up from outdated options/commands. Signed-off-by: Simon Hausmann <simon@lst.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Simon Hausmann committed
Aug 24, 2008 at 16:12 UTC
f5f7e4a18cf656747be8f8447ca304ddf716c742
1 file changed
+38
-31
contrib/fast-import/git-p4.txt
+38
-31
@@ -3,14 +3,16 @@ git-p4 - Perforce <-> Git converter using git-fast-import
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".
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
13
-You can simply start with
15
+Simply start with
16
17
git-p4 clone //depot/path/project
18
@@ -18,11 +20,18 @@ or
20
21
git-p4 clone //depot/path/project myproject
22
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:
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
@@ -37,31 +46,40 @@ If you want more control you can also use the git-p4 sync command directly:
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
40
---branch=mybranch option to use a different branch.
49
+--branch=mybranch option to import into a different branch.
50
42
-If you want to import the entire history of a given depot path just use
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
49
-Support for Perforce integrations is still work in progress. Don't bother
50
-trying it unless you want to hack on it :)
51
-
61
Incremental Imports
62
===================
63
55
-After an initial import you can easily synchronize your git repository with
56
-newer changes from the Perforce depot by just calling
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
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.
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
========
@@ -79,7 +97,7 @@ Submitting
97
==========
98
99
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
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
@@ -97,17 +115,6 @@ continue importing the remaining changes with
115
116
git-p4 submit --continue
117
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
-
118
Example
119
=======
120