{"thread":{"id":"29079","subject":"[RFC PATCH] git-p4: introduce asciidoc documentation","startedAt":"2011-12-03T23:53:28Z","lastAt":"2011-12-07T15:36:59Z","messageCount":5,"participants":["Pete Wyckoff","Frans Klaver","Luke Diamand"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"180289","messageId":"20111203235328.GA3866@arf.padd.com","threadId":"29079","inReplyTo":null,"subject":"[RFC PATCH] git-p4: introduce asciidoc documentation","fromName":"Pete Wyckoff","fromEmail":"pw@padd.com","sentAt":"2011-12-03T23:53:28Z","receivedAt":"2011-12-03T23:53:28Z","isPatch":true,"sender":{"key":"pw@padd.com","avatar":null},"body":"Add proper documentation for git-p4.  Delete the old .txt\ndocumentation from contrib/fast-import.\n---\n\nI'd appreciate review by git-p4 people to make sure I captured\neverything from the old documentation, and to catch any errors.\nThere's a fair amount of new content in here, describing all\nthe options and variables.  I left out some obscure commands\non purpose.\n\nComments from anyone else would be welcome too.  Especially\nin the area of generic asciidoc formatting or style in git\ncommand pages.\n\nThanks,\n\t\t-- Pete\n\n Documentation/git-p4.txt       |  456 ++++++++++++++++++++++++++++++++++++++++\n contrib/fast-import/git-p4.txt |  289 -------------------------\n 2 files changed, 456 insertions(+), 289 deletions(-)\n create mode 100644 Documentation/git-p4.txt\n delete mode 100644 contrib/fast-import/git-p4.txt\n\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nnew file mode 100644\nindex 0000000..c555dce\n--- /dev/null\n+++ b/Documentation/git-p4.txt\n@@ -0,0 +1,456 @@\n+git-p4(1)\n+=========\n+\n+NAME\n+----\n+git-p4 - Import from and submit to Perforce repositories\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...\n+'git p4 sync' [<sync options>] [<p4 depot path>...]\n+'git p4 rebase'\n+'git p4 submit' [<submit options>] [<master branch name>]\n+\n+\n+DESCRIPTION\n+-----------\n+This command provides a way to interact with p4 repositories\n+using git.\n+\n+Create a new git repository from an existing p4 repository using\n+'git p4 clone', giving it one or more p4 depot paths.  Incorporate\n+new commits from p4 changes with 'git p4 sync'.  The 'sync' command\n+is also used to include new branches from other p4 depot paths.\n+Submit git changes back to p4 using 'git p4 submit'.  The command\n+'git p4 rebase' does a sync plus rebases the current branch onto\n+the updated p4 remote branch.\n+\n+\n+EXAMPLE\n+-------\n+* Create an alias for 'git p4', using the full path to the 'git-p4'\n+  script if needed:\n++\n+------------\n+$ git config --global alias.p4 '!git-p4'\n+------------\n+\n+* Clone a repository:\n++\n+------------\n+$ git p4 clone //depot/path/project\n+------------\n+\n+* Do some work in the newly created git repository:\n++\n+------------\n+$ cd project\n+$ vi foo.h\n+$ git commit -a -m \"edited foo.h\"\n+------------\n+\n+* Update the git repository with recent changes from p4, rebasing your\n+  work on top:\n++\n+------------\n+$ git p4 rebase\n+------------\n+\n+* Submit your commits back to p4:\n++\n+------------\n+$ git p4 submit\n+------------\n+\n+\n+COMMANDS\n+--------\n+\n+Clone\n+~~~~~\n+Generally, 'git p4 clone' is used to create a new git directory\n+from an existing p4 repository:\n+------------\n+$ git p4 clone //depot/path/project\n+------------\n+This:\n+\n+1.   Creates an empty git repository in a subdirectory called 'project'.\n++\n+2.   Imports the full contents of the head revision from the given p4\n+depot path into a single commit in the git branch 'refs/remotes/p4/master'.\n++\n+3.   Creates a local branch, 'master' from this remote and checks it out.\n+\n+To reproduce the entire p4 history in git, use the '@all' modifier on\n+the depot path:\n+------------\n+$ git p4 clone //depot/path/project@all\n+------------\n+\n+\n+Sync\n+~~~~\n+As development continues in the p4 repository, those changes can\n+be included in the git repository using:\n+------------\n+$ git p4 sync\n+------------\n+This command finds new changes in p4 and imports them as git commits.\n+\n+P4 repositories can be added to an existing git repository using\n+'git p4 sync' too:\n+------------\n+$ mkdir repo-git\n+$ cd repo-git\n+$ git init\n+$ git p4 sync //path/in/your/perforce/depot\n+------------\n+This imports the specified depot into\n+'refs/remotes/p4/master' in an existing git repository.  The\n+'--branch' option can be used to specify a different branch to\n+be used for the p4 content.\n+\n+If a git repository includes branches 'refs/remotes/origin/p4', these\n+will be fetched and consulted first during a 'git p4 sync'.  Since\n+importing directly from p4 is considerably slower than pulling changes\n+from a git remote, this can be useful in a multi-developer environment.\n+\n+\n+Rebase\n+~~~~~~\n+A common working pattern is to fetch the latest changes from the p4 depot\n+and merge them with local uncommitted changes.  Often, the p4 repository\n+is the ultimate location for all code, thus a rebase workflow makes\n+sense.  This command does 'git p4 sync' followed by 'git rebase' to move\n+local commits on top of updated p4 changes.\n+------------\n+$ git p4 rebase\n+------------\n+\n+\n+Submit\n+~~~~~~\n+Submitting changes from a git repository back to the p4 repository\n+requires a separate p4 client workspace.  This should be specified\n+using the 'P4CLIENT' environment variable or the git configuration\n+variable 'git-p4.client'.  The p4 client must exist, but the client root\n+will be created and populated if it does not already exist.\n+\n+To submit all changes that are in the current git branch but not in\n+the 'p4/master' branch, use:\n+------------\n+$ git p4 submit\n+------------\n+\n+To specify a branch other than the current one, use:\n+------------\n+$ git p4 submit topicbranch\n+------------\n+\n+The upstream reference is generally 'refs/remotes/p4/master', but can\n+be overridden using the '--origin=' command-line option.\n+\n+The p4 changes will be created as the user invoking 'git p4 submit'. The\n+'--preserve-user' option will cause ownership to be modified\n+according to the author of the git commit.  This option requires admin\n+priviliges in p4, which can be granted using 'p4 protect'.\n+\n+\n+OPTIONS\n+-------\n+\n+General options\n+~~~~~~~~~~~~~~~\n+All commands except clone accept this option.\n+\n+--git-dir <dir>::\n+\tSet the 'GIT_DIR' environment variable.  See linkgit:git[1].\n+\n+Sync options\n+~~~~~~~~~~~~\n+These options can be used in the initial 'clone' as well as in\n+subsequent 'sync' operations.\n+\n+--branch <branch>::\n+\tImport changes into given branch.  If the branch starts with\n+\t'refs/', it will be used as is, otherwise the path 'refs/heads/'\n+\twill be prepended.  The default branch is 'master'.\n+\n+--detect-branches::\n+\tUse the branch detection algorithm to find new paths in p4.  It is\n+\tdocumented below in \"BRANCH DETECTION\".\n+\n+--changesfile <file>::\n+\tImport exactly the p4 change numbers listed in 'file', one per\n+\tline.  Normally, 'git p4' inspects the current p4 repository\n+\tstate and detects the changes it should import.\n+\n+--silent::\n+\tDo not print any progress information.\n+\n+--verbose::\n+\tProvide more progress information.\n+\n+--detect-labels::\n+\tQuery p4 for labels associated with the depot paths, and add\n+\tthem as tags in git.\n+\n+--import-local::\n+\tBy default, p4 branches are stored in 'refs/remotes/p4/',\n+\twhere they will be treated as remote-tracking branches by\n+\tlinkgit:git-branch[1] and other commands.  This option instead\n+\tputs p4 branches in 'refs/heads/p4/'.\n+\n+--max-changes <n>::\n+\tLimit the number of imported changes to 'n'.  Useful to\n+\tlimit the amount of history when using the '@all' p4 revision\n+\tspecifier.\n+\n+--keep-path::\n+\tThe mapping of file names from the p4 depot path to git, by\n+\tdefault, involves removing the entire depot path.  With this\n+\toption, the full p4 depot path is retained in git.  For example,\n+\tpath '//depot/main/foo/bar.c', when imported from\n+\t'//depot/main/', becomes 'foo/bar.c'.  With '--keep-path', the\n+\tgit path is instead 'depot/main/foo/bar.c'.\n+\n+--use-client-spec::\n+\tUse a client spec to find the list of interesting files in p4.\n+\tThe client spec is discovered using 'p4 client -o' which checks\n+\tthe 'P4CLIENT' environment variable and returns a mapping of\n+\tdepot files to workspace files.\n+\n+Clone options\n+~~~~~~~~~~~~~\n+These options can used in an initial 'clone', along with the 'sync'\n+options described above.\n+\n+--destination <directory>::\n+\tWhere to create the git repository.  If not provided, the last\n+\tcomponent in the p4 depot path is used to create a new\n+\tdirectory.\n+\n+--bare::\n+\tPerform a bare clone.  See linkgit:git-clone[1].\n+\n+-/ <path>::\n+\tExclude selected depot paths when cloning.\n+\n+Submit options\n+~~~~~~~~~~~~~~\n+These options can be used to modify 'git p4 submit' behavior.\n+\n+--verbose::\n+\tProvide more progress information.\n+\n+--origin <commit>::\n+\tUpstream location from which commits are identified to submit to\n+\tp4.  By default, this is the most recent p4 commit reachable\n+\tfrom 'HEAD'.\n+\n+-M[<n>]::\n+\tDetect renames.  See linkgit:git-diff[1].  Renames will be\n+\trepresented in p4 using explicit 'move' operations.\n+\n+--preserve-user::\n+\tRe-author p4 changes before submitting to p4.  This option\n+\trequires p4 admin priviliges.\n+\n+\n+DEPOT PATH SYNTAX\n+-----------------\n+The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can\n+be one or more space-separated p4 depot paths, with an optional\n+p4 revision specifier on the end:\n+\n+\"//depot/my/project\"::\n+    Import one commit with all files in the '#head' change under that tree.\n+\n+\"//depot/my/project@all\"::\n+    Import one commit for each change in the history of that depot path.\n+\n+\"//depot/my/project@1,6\"::\n+    Import only changes 1 through 6.\n+\n+\"//depot/proj1 //depot/proj2@all\"::\n+    Import all changes from both named depot paths.\n+\n+See 'p4 help revisions' for the full syntax of p4 revision specifiers.\n+\n+\n+BRANCH DETECTION\n+----------------\n+P4 does not have the same concept of a branch as git.  Instead,\n+p4 organizes its content as a directory tree, where by convention\n+different logical branches are in different locations in the tree.\n+The 'p4 branch' command is used to maintain mappings between\n+different areas in the tree, and indicate related content.  'git p4'\n+can use these mappings to determine branch relationships.\n+\n+If you have a repository where all the branches of interest exist as\n+subdirectories of a single depot path, you can use '--detect-branches'\n+when cloning or syncing to have 'git p4' automatically find\n+subdirectories in p4, and to generate these as branches in git.\n+\n+For example, if the P4 repository structure is:\n+----\n+//depot/main/...\n+//depot/branch1/...\n+----\n+\n+And \"p4 branch -o branch1\" shows a View line that looks like:\n+----\n+//depot/main/... //depot/branch1/...\n+----\n+\n+Then this 'git p4 clone' command:\n+----\n+git p4 clone --detect-branches //depot@all\n+----\n+produces a separate branch in 'refs/remotes/p4/' for //depot/main,\n+called 'master', and one for //depot/branch1 called 'depot/branch1'.\n+\n+However, it is not necessary to create branches in p4 to be able to use\n+them like branches.  Because it is difficult to infer branch\n+relationships automatically, a git configuration setting\n+'git-p4.branchList' can be used to explicitly identify branch\n+relationships.  It is a list of \"source:destination\" pairs, like a\n+simple p4 branch specification, where the \"source\" and \"destination\" are\n+the path elements in the p4 repository.  The example above relied on the\n+presence of the p4 branch.  Without p4 branches, the same result will\n+occur with:\n+----\n+git config git-p4.branchList main:branch1\n+git p4 clone --detect-branches //depot@all\n+----\n+\n+\n+PERFORMANCE\n+-----------\n+The fast-import mechanism used by 'git p4' creates one pack file for\n+each invocation of 'git p4 sync'.  Normally, git garbage compression\n+(linkgit:git-gc[1]) automatically compresses these to fewer pack files,\n+but explicit invocation of 'git repack -adf' may improve performance.\n+\n+\n+CONFIGURATION VARIABLES\n+-----------------------\n+The following config settings can be used to modify 'git p4' behavior.\n+They all are in the 'git-p4' section.\n+\n+General variables\n+~~~~~~~~~~~~~~~~~\n+git-p4.user::\n+\tUser specified as an option to all p4 commands, with '-u <user>'.\n+\tThe environment variable 'P4USER' can be used instead.\n+\n+git-p4.password::\n+\tPassword specified as an option to all p4 commands, with\n+\t'-P <password>'.\n+\tThe environment variable 'P4PASS' can be used instead.\n+\n+git-p4.port::\n+\tPort specified as an option to all p4 commands, with\n+\t'-p <port>'.\n+\tThe environment variable 'P4PORT' can be used instead.\n+\n+git-p4.host::\n+\tHost specified as an option to all p4 commands, with\n+\t'-h <host>'.\n+\tThe environment variable 'P4HOST' can be used instead.\n+\n+git-p4.client::\n+\tClient specified as an option to all p4 commands, with\n+\t'-c <client>'.  This can also be used as a way to find\n+\tthe client spec for the 'useClientSpec' option.\n+\tThe environment variable 'P4CLIENT' can be used instead.\n+\n+Clone and sync variables\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+git-p4.syncFromOrigin::\n+\tBecause importing commits from other git repositories is much faster\n+\tthan importing them from p4, a mechanism exists to find p4 changes\n+\tfirst in git remotes.  If branches exist under 'refs/remote/origin/p4',\n+\tthose will be fetched and used when syncing from p4.  This\n+\tvariable can be set to 'false' to disable this behavior.\n+\n+git-p4.branchUser::\n+\tOne phase in branch detection involves looking at p4 branches\n+\tto find new ones to import.  By default, all branches are\n+\tinspected.  This option limits the search to just those owned\n+\tby the single user named in the variable.\n+\n+git-p4.branchList::\n+\tList of branches to be imported when branch detection is\n+\tenabled.  Each entry should be a pair of branch names separated\n+\tby a colon (:).  This example declares that both branchA and\n+\tbranchB were created from main:\n+-------------\n+git config       git-p4.branchList main:branchA\n+git config --add git-p4.branchList main:branchB\n+-------------\n+\n+git-p4.useClientSpec::\n+\tSpecify that the p4 client spec to be used to identify p4 depot\n+\tpaths of interest.  This is equivalent to specifying the option\n+\t'--use-client-spec'.  The variable 'git-p4.client' can be used\n+\tto specify the name of the client.\n+\n+Submit variables\n+~~~~~~~~~~~~~~~\n+git-p4.detectRenames::\n+\tDetect renames.  See linkgit:git-diff[1].\n+\n+git-p4.detectCopies::\n+\tDetect copies.  See linkgit:git-diff[1].\n+\n+git-p4.detectCopiesHarder::\n+\tDetect copies harder.  See linkgit:git-diff[1].\n+\n+git-p4.preserveUser::\n+\tOn submit, re-author changes to reflect the git author,\n+\tregardless of who invokes 'git p4 submit'.\n+\n+git-p4.allowMissingP4Users::\n+\tWhen 'preserveUser' is true, 'git p4' normally dies if it\n+\tcannot find an author in the p4 user map.  This setting\n+\tsubmits the change regardless.\n+\n+git-p4.skipSubmitEdit::\n+\tThe submit process invokes the editor before each p4 change\n+\tis submitted.  If this setting is true, though, the editing\n+\tstep is skipped.\n+\n+git-p4.skipSubmitEditCheck::\n+\tAfter editing the p4 change message, 'git p4' makes sure that\n+\tthe description really was changed by looking at the file\n+\tmodification time.  This option disables that test.\n+\n+git-p4.allowSubmit::\n+\tBy default, any branch can be used as the source for a 'git p4\n+\tsubmit' operation.  This configuration variable , if set, permits only\n+\tthe named branches to be used as submit sources.\n+\n+git-p4.skipUserNameCheck::\n+\tIf the user running 'git p4 submit' does not exist in the p4\n+\tuser map, 'git p4' exits.  This option can be used to force\n+\tsubmission regardless.\n+\n+\n+IMPLEMENTATION DETAILS\n+----------------------\n+* Changesets from p4 are imported using git fast-import.\n+* Cloning or syncing does not require a p4 client; file contents are\n+  collected using 'p4 print'.\n+* Submitting requires a p4 client, which is not in the same location\n+  as the git repository.  Patches are applied, one at a time, to\n+  this p4 client and submitted from there.\n+* Each commit imported by 'git p4' has a line at the end of the log\n+  message indicating the p4 depot location and change number.  This\n+  line is used by later 'git p4 sync' operations to know which p4\n+  changes are new.\n+\ndiff --git a/contrib/fast-import/git-p4.txt b/contrib/fast-import/git-p4.txt\ndeleted file mode 100644\nindex 52003ae..0000000\n--- a/contrib/fast-import/git-p4.txt\n+++ /dev/null\n@@ -1,289 +0,0 @@\n-git-p4 - Perforce <-> Git converter using git-fast-import\n-\n-Usage\n-=====\n-\n-git-p4 can be used in two different ways:\n-\n-1) To import changes from Perforce to a Git repository, using \"git-p4 sync\".\n-\n-2) To submit changes from Git back to Perforce, using \"git-p4 submit\".\n-\n-Importing\n-=========\n-\n-Simply start with\n-\n-  git-p4 clone //depot/path/project\n-\n-or\n-\n-  git-p4 clone //depot/path/project myproject\n-\n-This will:\n-\n-1) Create an empty git repository in a subdirectory called \"project\" (or\n-\"myproject\" with the second command)\n-\n-2) Import the head revision from the given Perforce path into a git branch\n-called \"p4\" (remotes/p4 actually)\n-\n-3) Create a master branch based on it and check it out.\n-\n-If you want the entire history (not just the head revision) then you can simply\n-append a \"@all\" to the depot path:\n-\n-  git-p4 clone //depot/project/main@all myproject\n-\n-\n-\n-If you want more control you can also use the git-p4 sync command directly:\n-\n-  mkdir repo-git\n-  cd repo-git\n-  git init\n-  git-p4 sync //path/in/your/perforce/depot\n-\n-This will import the current head revision of the specified depot path into a\n-\"remotes/p4/master\" branch of your git repository. You can use the\n---branch=mybranch option to import into a different branch.\n-\n-If you want to import the entire history of a given depot path simply use:\n-\n-  git-p4 sync //path/in/depot@all\n-\n-\n-Note:\n-\n-To achieve optimal compression you may want to run 'git repack -a -d -f' after\n-a big import. This may take a while.\n-\n-Incremental Imports\n-===================\n-\n-After an initial import you can continue to synchronize your git repository\n-with newer changes from the Perforce depot by just calling\n-\n-  git-p4 sync\n-\n-in your git repository. By default the \"remotes/p4/master\" branch is updated.\n-\n-Advanced Setup\n-==============\n-\n-Suppose you have a periodically updated git repository somewhere, containing a\n-complete import of a Perforce project. This repository can be cloned and used\n-with git-p4. When updating the cloned repository with the \"sync\" command,\n-git-p4 will try to fetch changes from the original repository first. The git\n-protocol used with this is usually faster than importing from Perforce\n-directly.\n-\n-This behaviour can be disabled by setting the \"git-p4.syncFromOrigin\" git\n-configuration variable to \"false\".\n-\n-Updating\n-========\n-\n-A common working pattern is to fetch the latest changes from the Perforce depot\n-and merge them with local uncommitted changes. The recommended way is to use\n-git's rebase mechanism to preserve linear history. git-p4 provides a convenient\n-\n-  git-p4 rebase\n-\n-command that calls git-p4 sync followed by git rebase to rebase the current\n-working branch.\n-\n-Submitting\n-==========\n-\n-git-p4 has support for submitting changes from a git repository back to the\n-Perforce depot. This requires a Perforce checkout separate from your git\n-repository. To submit all changes that are in the current git branch but not in\n-the \"p4\" branch (or \"origin\" if \"p4\" doesn't exist) simply call\n-\n-    git-p4 submit\n-\n-in your git repository. If you want to submit changes in a specific branch that\n-is not your current git branch you can also pass that as an argument:\n-\n-    git-p4 submit mytopicbranch\n-\n-You can override the reference branch with the --origin=mysourcebranch option.\n-\n-The Perforce changelists will be created with the user who ran git-p4. If you\n-use --preserve-user then git-p4 will attempt to create Perforce changelists\n-with the Perforce user corresponding to the git commit author. You need to\n-have sufficient permissions within Perforce, and the git users need to have\n-Perforce accounts. Permissions can be granted using 'p4 protect'.\n-\n-If a submit fails you may have to \"p4 resolve\" and submit manually. You can\n-continue importing the remaining changes with\n-\n-  git-p4 submit --continue\n-\n-Example\n-=======\n-\n-# Clone a repository\n-  git-p4 clone //depot/path/project\n-# Enter the newly cloned directory\n-  cd project\n-# Do some work...\n-  vi foo.h\n-# ... and commit locally to gi\n-  git commit foo.h\n-# In the meantime somebody submitted changes to the Perforce depot. Rebase your latest\n-# changes against the latest changes in Perforce:\n-  git-p4 rebase\n-# Submit your locally committed changes back to Perforce\n-  git-p4 submit\n-# ... and synchronize with Perforce\n-  git-p4 rebase\n-\n-\n-Configuration parameters\n-========================\n-\n-git-p4.user ($P4USER)\n-\n-Allows you to specify the username to use to connect to the Perforce repository.\n-\n-  git config [--global] git-p4.user public\n-\n-git-p4.password ($P4PASS)\n-\n-Allows you to specify the password to use to connect to the Perforce repository.\n-Warning this password will be visible on the command-line invocation of the p4 binary.\n-\n-  git config [--global] git-p4.password public1234\n-\n-git-p4.port ($P4PORT)\n-\n-Specify the port to be used to contact the Perforce server. As this will be passed\n-directly to the p4 binary, it may be in the format host:port as well.\n-\n-  git config [--global] git-p4.port codes.zimbra.com:2666\n-\n-git-p4.host ($P4HOST)\n-\n-Specify the host to contact for a Perforce repository.\n-\n-  git config [--global] git-p4.host perforce.example.com\n-\n-git-p4.client ($P4CLIENT)\n-\n-Specify the client name to use\n-\n-  git config [--global] git-p4.client public-view\n-\n-git-p4.allowSubmit\n-\n-  git config [--global] git-p4.allowSubmit false\n-\n-git-p4.syncFromOrigin\n-\n-A useful setup may be that you have a periodically updated git repository\n-somewhere that contains a complete import of a Perforce project. That git\n-repository can be used to clone the working repository from and one would\n-import from Perforce directly after cloning using git-p4. If the connection to\n-the Perforce server is slow and the working repository hasn't been synced for a\n-while it may be desirable to fetch changes from the origin git repository using\n-the efficient git protocol. git-p4 supports this setup by calling \"git fetch origin\"\n-by default if there is an origin branch. You can disable this using:\n-\n-  git config [--global] git-p4.syncFromOrigin false\n-\n-git-p4.useclientspec\n-\n-  git config [--global] git-p4.useclientspec false\n-\n-The P4CLIENT environment variable should be correctly set for p4 to be\n-able to find the relevant client.  This client spec will be used to\n-both filter the files cloned by git and set the directory layout as\n-specified in the client (this implies --keep-path style semantics).\n-\n-git-p4.skipSubmitModTimeCheck\n-\n-  git config [--global] git-p4.skipSubmitModTimeCheck false\n-\n-If true, submit will not check if the p4 change template has been modified.\n-\n-git-p4.preserveUser\n-\n-  git config [--global] git-p4.preserveUser false\n-\n-If true, attempt to preserve user names by modifying the p4 changelists. See\n-the \"--preserve-user\" submit option.\n-\n-git-p4.allowMissingPerforceUsers\n-\n-  git config [--global] git-p4.allowMissingP4Users false\n-\n-If git-p4 is setting the perforce user for a commit (--preserve-user) then\n-if there is no perforce user corresponding to the git author, git-p4 will\n-stop. With allowMissingPerforceUsers set to true, git-p4 will use the\n-current user (i.e. the behavior without --preserve-user) and carry on with\n-the perforce commit.\n-\n-git-p4.skipUserNameCheck\n-\n-  git config [--global] git-p4.skipUserNameCheck false\n-\n-When submitting, git-p4 checks that the git commits are authored by the current\n-p4 user, and warns if they are not. This disables the check.\n-\n-git-p4.detectRenames\n-\n-Detect renames when submitting changes to Perforce server. Will enable -M git\n-argument. Can be optionally set to a number representing the threshold\n-percentage value of the rename detection.\n-\n-  git config [--global] git-p4.detectRenames true\n-  git config [--global] git-p4.detectRenames 50\n-\n-git-p4.detectCopies\n-\n-Detect copies when submitting changes to Perforce server. Will enable -C git\n-argument. Can be optionally set to a number representing the threshold\n-percentage value of the copy detection.\n-\n-  git config [--global] git-p4.detectCopies true\n-  git config [--global] git-p4.detectCopies 80\n-\n-git-p4.detectCopiesHarder\n-\n-Detect copies even between files that did not change when submitting changes to\n-Perforce server. Will enable --find-copies-harder git argument.\n-\n-  git config [--global] git-p4.detectCopies true\n-\n-git-p4.branchUser\n-\n-Only use branch specifications defined by the selected username.\n-\n-  git config [--global] git-p4.branchUser username\n-\n-git-p4.branchList\n-\n-List of branches to be imported when branch detection is enabled.\n-\n-  git config [--global] git-p4.branchList main:branchA\n-  git config [--global] --add git-p4.branchList main:branchB\n-\n-Implementation Details...\n-=========================\n-\n-* Changesets from Perforce are imported using git fast-import.\n-* The import does not require anything from the Perforce client view as it just uses\n-  \"p4 print //depot/path/file#revision\" to get the actual file contents.\n-* Every imported changeset has a special [git-p4...] line at the\n-  end of the log message that gives information about the corresponding\n-  Perforce change number and is also used by git-p4 itself to find out\n-  where to continue importing when doing incremental imports.\n-  Basically when syncing it extracts the perforce change number of the\n-  latest commit in the \"p4\" branch and uses \"p4 changes //depot/path/...@changenum,#head\"\n-  to find out which changes need to be imported.\n-* git-p4 submit uses \"git rev-list\" to pick the commits between the \"p4\" branch\n-  and the current branch.\n-  The commits themselves are applied using git diff/format-patch ... | git apply\n-\n-- \n1.7.8.rc4.30.g3c9dc\n"},{"id":"180297","messageId":"op.v5zh6udk0aolir@keputer","threadId":"29079","inReplyTo":"20111203235328.GA3866@arf.padd.com","subject":"Re: [RFC PATCH] git-p4: introduce asciidoc documentation","fromName":"Frans Klaver","fromEmail":"fransklaver@gmail.com","sentAt":"2011-12-04T21:33:56Z","receivedAt":"2011-12-04T21:33:56Z","isPatch":true,"sender":{"key":"fransklaver@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1876483?v=4"},"body":"> +Clone options\n> +~~~~~~~~~~~~~\n> +These options can used in an initial 'clone', along with the 'sync\n\ns/can used/can be used/\n\nCheers,\nFrans\n"},{"id":"180298","messageId":"20111204214903.GA17331@arf.padd.com","threadId":"29079","inReplyTo":"op.v5zh6udk0aolir@keputer","subject":"Re: [RFC PATCH] git-p4: introduce asciidoc documentation","fromName":"Pete Wyckoff","fromEmail":"pw@padd.com","sentAt":"2011-12-04T21:49:03Z","receivedAt":"2011-12-04T21:49:03Z","isPatch":true,"sender":{"key":"pw@padd.com","avatar":null},"body":"fransklaver@gmail.com wrote on Sun, 04 Dec 2011 22:33 +0100:\n> >+Clone options\n> >+~~~~~~~~~~~~~\n> >+These options can used in an initial 'clone', along with the 'sync\n> \n> s/can used/can be used/\n\nThanks for checking.  I'll roll it in with the next submission.\n\n\t\t-- Pete\n"},{"id":"180475","messageId":"4EDF3611.3000902@diamand.org","threadId":"29079","inReplyTo":"20111203235328.GA3866@arf.padd.com","subject":"Re: [RFC PATCH] git-p4: introduce asciidoc documentation","fromName":"Luke Diamand","fromEmail":"luke@diamand.org","sentAt":"2011-12-07T09:46:57Z","receivedAt":"2011-12-07T09:46:57Z","isPatch":true,"sender":{"key":"luke@diamand.org","avatar":"https://avatars.githubusercontent.com/u/5330967?v=4"},"body":"On 03/12/11 23:53, Pete Wyckoff wrote:\n> Add proper documentation for git-p4.  Delete the old .txt\n> documentation from contrib/fast-import.\n> ---\n>\n> I'd appreciate review by git-p4 people to make sure I captured\n> everything from the old documentation, and to catch any errors.\n> There's a fair amount of new content in here, describing all\n> the options and variables.  I left out some obscure commands\n> on purpose.\n>\n> Comments from anyone else would be welcome too.  Especially\n> in the area of generic asciidoc formatting or style in git\n> command pages.\n\nThat looks good to me, I can't see anything of note, just one minor nit, \nbelow.\n\nLuke\n\n\n>\n> Thanks,\n> \t\t-- Pete\n>\n>   Documentation/git-p4.txt       |  456 ++++++++++++++++++++++++++++++++++++++++\n>   contrib/fast-import/git-p4.txt |  289 -------------------------\n>   2 files changed, 456 insertions(+), 289 deletions(-)\n>   create mode 100644 Documentation/git-p4.txt\n>   delete mode 100644 contrib/fast-import/git-p4.txt\n> +\n>\n> +------------\n> +$ cd project\n> +$ vi foo.h\n\nI think it works with other editors as well, although I've not tried it \nmyself. Obviously with reduced functionality :-)\n\n\n> +git-p4.allowSubmit::\n> +\tBy default, any branch can be used as the source for a 'git p4\n> +\tsubmit' operation.  This configuration variable , if set, permits only\n\nSpacing around comma in \"variable , if set\"\n\nLuke\n"},{"id":"180488","messageId":"20111207153659.GA16841@arf.padd.com","threadId":"29079","inReplyTo":"4EDF3611.3000902@diamand.org","subject":"Re: [RFC PATCH] git-p4: introduce asciidoc documentation","fromName":"Pete Wyckoff","fromEmail":"pw@padd.com","sentAt":"2011-12-07T15:36:59Z","receivedAt":"2011-12-07T15:36:59Z","isPatch":true,"sender":{"key":"pw@padd.com","avatar":null},"body":"luke@diamand.org wrote on Wed, 07 Dec 2011 09:46 +0000:\n> On 03/12/11 23:53, Pete Wyckoff wrote:\n> >Add proper documentation for git-p4.  Delete the old .txt\n> >documentation from contrib/fast-import.\n> >---\n> >+------------\n> >+$ cd project\n> >+$ vi foo.h\n> \n> I think it works with other editors as well, although I've not tried\n> it myself. Obviously with reduced functionality :-)\n\nQuite.  :)\n\n> >+git-p4.allowSubmit::\n> >+\tBy default, any branch can be used as the source for a 'git p4\n> >+\tsubmit' operation.  This configuration variable , if set, permits only\n> \n> Spacing around comma in \"variable , if set\"\n\nThanks, queued up.\n\nI've got 8 more patches to the docs and code, adding unit tests\nas I figure out quirks of all the existing options for\nsync/clone.  I'll continue with the submit options next then\nsend them all out for review.\n\n\t\t-- Pete\n"}]}