diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.6.6.txt | 16 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.7.6.txt | 20 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.8.2.txt | 71 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.8.3.txt | 16 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.8.4.txt | 23 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.9.txt | 114 | ||||
| -rw-r--r-- | Documentation/config.txt | 20 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-clone.txt | 11 | ||||
| -rw-r--r-- | Documentation/git-grep.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-mailinfo.txt | 25 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 498 | ||||
| -rw-r--r-- | Documentation/git-read-tree.txt | 11 | ||||
| -rw-r--r-- | Documentation/git-show-ref.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-submodule.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 8 | ||||
| -rw-r--r-- | Documentation/git.txt | 14 | ||||
| -rw-r--r-- | Documentation/howto/using-signed-tag-in-pull-request.txt | 217 |
19 files changed, 969 insertions, 119 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 116f17587e..d40e211f22 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -20,7 +20,10 @@ ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. -SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual +SP_ARTICLES = user-manual +SP_ARTICLES += howto/revert-branch-rebase +SP_ARTICLES += howto/using-merge-subtree +SP_ARTICLES += howto/using-signed-tag-in-pull-request API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/RelNotes/1.7.6.6.txt b/Documentation/RelNotes/1.7.6.6.txt new file mode 100644 index 0000000000..5343e00400 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.6.txt @@ -0,0 +1,16 @@ +Git v1.7.6.6 Release Notes +========================== + +Fixes since v1.7.6.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.6.txt b/Documentation/RelNotes/1.7.7.6.txt new file mode 100644 index 0000000000..8df606d452 --- /dev/null +++ b/Documentation/RelNotes/1.7.7.6.txt @@ -0,0 +1,20 @@ +Git v1.7.7.6 Release Notes +========================== + +Fixes since v1.7.7.5 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.2.txt b/Documentation/RelNotes/1.7.8.2.txt new file mode 100644 index 0000000000..e74f4ef1ef --- /dev/null +++ b/Documentation/RelNotes/1.7.8.2.txt @@ -0,0 +1,71 @@ +Git v1.7.8.2 Release Notes +========================== + +Fixes since v1.7.8.1 +-------------------- + + * Porcelain commands like "git reset" did not distinguish deletions + and type-changes from ordinary modification, and reported them with + the same 'M' moniker. They now use 'D' (for deletion) and 'T' (for + type-change) to match "git status -s" and "git diff --name-status". + + * The configuration file parser used for sizes (e.g. bigFileThreshold) + did not correctly interpret 'g' suffix. + + * The replacement implemention for snprintf used on platforms with + native snprintf that is broken did not use va_copy correctly. + + * LF-to-CRLF streaming filter replaced all LF with CRLF, which might + be techinically correct but not friendly to people who are trying + to recover from earlier mistakes of using CRLF in the repository + data in the first place. It now refrains from doing so for LF that + follows a CR. + + * git native connection going over TCP (not over SSH) did not set + SO_KEEPALIVE option which failed to receive link layer errors. + + * "git branch -m <current branch> HEAD" is an obvious no-op but was not + allowed. + + * "git checkout -m" did not recreate the conflicted state in a "both + sides added, without any common ancestor version" conflict + situation. + + * "git cherry-pick $commit" (not a range) created an unnecessary + sequencer state and interfered with valid workflow to use the + command during a session to cherry-pick multiple commits. + + * You could make "git commit" segfault by giving the "--no-message" + option. + + * "fast-import" did not correctly update an existing notes tree, + possibly corrupting the fan-out. + + * "git fetch-pack" accepted unqualified refs that do not begin with + refs/ by mistake and compensated it by matching the refspec with + tail-match, which was doubly wrong. This broke fetching from a + repository with a funny named ref "refs/foo/refs/heads/master" and a + 'master' branch with "git fetch-pack refs/heads/master", as the + command incorrectly considered the former a "match". + + * "git log --follow" did not honor the rename threshold score given + with the -M option (e.g. "-M50%"). + + * "git mv" gave suboptimal error/warning messages when it overwrites + target files. It also did not pay attention to "-v" option. + + * Authenticated "git push" over dumb HTTP were broken with a recent + change and failed without asking for password when username is + given. + + * "git push" to an empty repository over HTTP were broken with a + recent change to the ref handling. + + * "git push -v" forgot how to be verbose by mistake. It now properly + becomes verbose when asked to. + + * When a "reword" action in "git rebase -i" failed to run "commit --amend", + we did not give the control back to the user to resolve the situation, and + instead kept the original commit log message. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.3.txt b/Documentation/RelNotes/1.7.8.3.txt new file mode 100644 index 0000000000..a92714c14b --- /dev/null +++ b/Documentation/RelNotes/1.7.8.3.txt @@ -0,0 +1,16 @@ +Git v1.7.8.3 Release Notes +========================== + +Fixes since v1.7.8.2 +-------------------- + + * Attempt to fetch from an empty file pretending it to be a bundle did + not error out correctly. + + * gitweb did not correctly fall back to configured $fallback_encoding + that is not 'latin1'. + + * "git clone --depth $n" did not catch a non-number given as $n as an + error. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.8.4.txt b/Documentation/RelNotes/1.7.8.4.txt new file mode 100644 index 0000000000..9bebdbf13d --- /dev/null +++ b/Documentation/RelNotes/1.7.8.4.txt @@ -0,0 +1,23 @@ +Git v1.7.8.4 Release Notes +========================== + +Fixes since v1.7.8.3 +-------------------- + + * The code to look up attributes for paths reused entries from a wrong + directory when two paths in question are in adjacent directories and + the name of the one directory is a prefix of the other. + + * A wildcard that matches deeper hierarchy given to the "diff-index" command, + e.g. "git diff-index HEAD -- '*.txt'", incorrectly reported additions of + matching files even when there is no change. + + * When producing a "thin pack" (primarily used in bundles and smart + HTTP transfers) out of a fully packed repository, we unnecessarily + avoided sending recent objects as a delta against objects we know + the other side has. + + * "git send-email" did not properly treat sendemail.multiedit as a + boolean (e.g. setting it to "false" did not turn it off). + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.txt b/Documentation/RelNotes/1.7.9.txt index 4f65956aa0..95320aad5d 100644 --- a/Documentation/RelNotes/1.7.9.txt +++ b/Documentation/RelNotes/1.7.9.txt @@ -1,4 +1,4 @@ -Git v1.7.9 Release Notes (draft) +Git v1.7.9 Release Notes ======================== Updates since v1.7.8 @@ -12,33 +12,30 @@ Updates since v1.7.8 * Git uses gettext to translate its most common interface messages into the user's language if translations are available and the - locale is appropriately set. Distributors can drop in new PO files + locale is appropriately set. Distributors can drop new PO files in po/ to add new translations. - * Porcelain commands like "git reset" did not distinguish deletions - and type-changes from ordinary modification, and reported them with - the same 'M' moniker. They now use 'D' (for deletion) and 'T' (for - type-change) to match "git status -s" and "git diff --name-status". - - * The code to handle username/password for HTTP transaction used in + * The code to handle username/password for HTTP transactions used in "git push" & "git fetch" learned to talk "credential API" to external programs to cache or store them, to allow integration with platform native keychain mechanisms. - * The prompted input in the terminal use our own getpass() replacement - when possible. HTTP transactions used to ask username without echoing - back what was typed, but with this change you will see it as you type. + * The input prompts in the terminal use our own getpass() replacement + when possible. HTTP transactions used to ask for the username without + echoing back what was typed, but with this change you will see it as + you type. - * The internal of "revert/cherry-pick" has been tweaked to prepare + * The internals of "revert/cherry-pick" have been tweaked to prepare building more generic "sequencer" on top of the implementation that drives them. + * "git rev-parse FETCH_HEAD" after "git fetch" without specifying + what to fetch from the command line will now show the commit that + would be merged if the command were "git pull". + * "git add" learned to stream large files directly into a packfile instead of writing them into individual loose object files. - * "git branch -m <current branch> HEAD" is an obvious no-op and is - now allowed. - * "git checkout -B <current branch> <elsewhere>" is a more intuitive way to spell "git reset --keep <elsewhere>". @@ -56,6 +53,9 @@ Updates since v1.7.8 * "git commit" detects and rejects an attempt to stuff NUL byte in the commit log message. + * "git commit" learned "-S" to GPG-sign the commit; this can be shown + with the "--show-signature" option to "git log". + * fsck and prune are relatively lengthy operations that still go silent while making the end-user wait. They learned to give progress output like other slow operations. @@ -63,11 +63,8 @@ Updates since v1.7.8 * The set of built-in function-header patterns for various languages knows MATLAB. - * "git log --follow" honors the rename threshold score given with the - -M option (e.g. "-M50%"). - * "git log --format='<format>'" learned new %g[nNeE] specifiers to - show information from the reflog entries when warlking the reflog + show information from the reflog entries when walking the reflog (i.e. with "-g"). * "git pull" can be used to fetch and merge an annotated/signed tag, @@ -75,6 +72,10 @@ Updates since v1.7.8 signed tag is recorded in the resulting merge commit for later auditing. + * "git log" learned "--show-signature" option to show the signed tag + that was merged that is embedded in the merge commit. It also can + show the signature made on the commit with "git commit -S". + * "git branch --edit-description" can be used to add descriptive text to explain what a topic branch is about. @@ -106,75 +107,6 @@ Also contains minor documentation updates and code clean-ups. Fixes since v1.7.8 ------------------ - * The replacement implemention for snprintf used on platforms with - native snprintf that is broken did not use va_copy correctly. - (merge a9bfbc5 jk/maint-snprintf-va-copy later to maint). - - * git native connection going over TCP (not over SSH) did not set - SO_KEEPALIVE option which failed to receive link layer errors. - (merge e47a858 ew/keepalive later to maint). - - * LF-to-CRLF streaming filter replaced all LF with CRLF, which might - be techinically correct but not friendly to people who are trying - to recover from earlier mistakes of using CRLF in the repository - data in the first place. It now refrains from doing so for LF that - follows a CR. - (merge 8496f56 jc/maint-lf-to-crlf-keep-crlf later to maint). - - * "git checkout -m" did not recreate the conflicted state in a "both - sides added, without any common ancestor version" conflict - situation. - (merge 5cd7fadc jc/checkout-m-twoway later to maint). - - * "git cherry-pick $commit" (not a range) created an unnecessary - sequencer state and interfered with valid workflow to use the - command during a session to cherry-pick multiple commits. - (merge d596118 jn/maint-sequencer-fixes later to maint). - - * You could make "git commit" segfault by giving the "--no-message" - option. - (merge 03f94ae jk/maint-strbuf-missing-init later to maint). - - * "fast-import" did not correctly update an existing notes tree, - possibly corrupting the fan-out. - - * "git fetch-pack" accepted unqualified refs that do not begin with - refs/ by mistake and compensated it by matching the refspec with - tail-match, which was doubly wrong. This broke fetching from a - repository with a funny named ref "refs/foo/refs/heads/master" and a - 'master' branch with "git fetch-pack refs/heads/master", as the - command incorrectly considered the former a "match". - (merge bab8d28 jk/fetch-no-tail-match-refs later to maint). - - * "git mv" gave suboptimal error/warning messages when it overwrites - target files. It also did not pay attention to "-v" option. - (merge 534376c jk/maint-mv later to maint). - - * When a "reword" action in "git rebase -i" failed to run "commit --amend", - we did not give the control back to the user to resolve the situation, and - instead kept the original commit log message. - (merge 0becb3e aw/rebase-i-stop-on-failure-to-amend later to maint). - - * Authenticated "git push" over dumb HTTP were broken with a recent - change and failed without asking for password when username is - given. - (merge a4ddbc3 jk/maint-push-over-dav later to maint). - - * "git push" to an empty repository over HTTP were broken with a - recent change to the ref handling. - (merge 02f7914 jk/http-push-to-empty later to maint). - - * "git push -v" forgot how to be verbose by mistake. It now properly is. - (merge bd2c86e jk/maint-push-v-is-verbose later to maint). - - * gitweb did not correctly fall back to configured $fallback_encoding - that is not 'latin1'. - (merge b13e3ea jn/maint-gitweb-utf8-fix later to maint). - --- -exec >/var/tmp/1 -O=v1.7.8.1-384-g2b6dd6a -echo O=$(git describe master) -git log --first-parent --oneline --reverse ^$O master -echo -git shortlog --no-merges ^$O ^maint master +Unless otherwise noted, all the fixes since v1.7.8 in the maintenance +releases are contained in this release (see release notes to them for +details). diff --git a/Documentation/config.txt b/Documentation/config.txt index 6e63b5938f..abeb82b2c6 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1123,6 +1123,17 @@ grep.lineNumber:: grep.extendedRegexp:: If set to true, enable '--extended-regexp' option by default. +gpg.program:: + Use this custom program instead of "gpg" found on $PATH when + making or verifying a PGP signature. The program must support the + same command line interface as GPG, namely, to verify a detached + signature, "gpg --verify $file - <$signature" is run, and the + program is expected to signal a good signature by exiting with + code 0, and to generate an ascii-armored detached signature, the + standard input of "gpg -bsau $key" is fed with the contents to be + signed, and the program is expected to send the result to its + standard output. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -1772,10 +1783,11 @@ rerere.autoupdate:: rerere.enabled:: Activate recording of resolved conflicts, so that identical - conflict hunks can be resolved automatically, should they - be encountered again. linkgit:git-rerere[1] command is by - default enabled if you create `rr-cache` directory under - `$GIT_DIR`, but can be disabled by setting this option to false. + conflict hunks can be resolved automatically, should they be + encountered again. By default, linkgit:git-rerere[1] is + enabled if there is an `rr-cache` directory under the + `$GIT_DIR`, e.g. if "rerere" was previously used in the + repository. sendemail.identity:: A configuration identity. When given, causes values in the diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 887466d777..ee6cca2e13 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -40,6 +40,9 @@ OPTIONS --keep:: Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--keep-non-patch:: + Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + --keep-cr:: --no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 4b8b26b75e..0931a3e392 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -13,7 +13,8 @@ SYNOPSIS [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--separate-git-dir <git dir>] - [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [--depth <depth>] [--[no-]single-branch] + [--recursive|--recurse-submodules] [--] <repository> [<directory>] DESCRIPTION @@ -179,6 +180,14 @@ objects from the source repository into a pack in the cloned repository. with a long history, and would want to send in fixes as patches. +--single-branch:: + Clone only the history leading to the tip of a single branch, + either specified by the `--branch` option or the primary + branch remote's `HEAD` points at. When creating a shallow + clone with the `--depth` option, this is the default, unless + `--no-single-branch` is given to fetch the histories near the + tips of all branches. + --recursive:: --recurse-submodules:: After the clone is created, initialize all submodules within, diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 15d6711d46..6a8b1e3a7d 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -79,6 +79,9 @@ OPTIONS --max-depth <depth>:: For each <pathspec> given on command line, descend at most <depth> levels of directories. A negative value means no limit. + This option is ignored if <pathspec> contains active wildcards. + In other words if "a*" matches a directory named "a*", + "*" is matched literally so --max-depth is still effective. -w:: --word-regexp:: diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 51dc325748..97e7a8e9e7 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -25,13 +25,24 @@ command directly. See linkgit:git-am[1] instead. OPTIONS ------- -k:: - Usually the program 'cleans up' the Subject: header line - to extract the title line for the commit log message, - among which (1) remove 'Re:' or 're:', (2) leading - whitespaces, (3) '[' up to ']', typically '[PATCH]', and - then prepends "[PATCH] ". This flag forbids this - munging, and is most useful when used to read back - 'git format-patch -k' output. + Usually the program removes email cruft from the Subject: + header line to extract the title line for the commit log + message. This option prevents this munging, and is most + useful when used to read back 'git format-patch -k' output. ++ +Specifically, the following are removed until none of them remain: ++ +-- +* Leading and trailing whitespace. + +* Leading `Re:`, `re:`, and `:`. + +* Leading bracketed strings (between `[` and `]`, usually + `[PATCH]`). +-- ++ +Finally, runs of whitespace are normalized to a single ASCII space +character. -b:: When -k is not in effect, all leading strings bracketed with '[' diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt new file mode 100644 index 0000000000..8b92cc0f8d --- /dev/null +++ b/Documentation/git-p4.txt @@ -0,0 +1,498 @@ +git-p4(1) +========= + +NAME +---- +git-p4 - Import from and submit to Perforce repositories + + +SYNOPSIS +-------- +[verse] +'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... +'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 rebase' +'git p4 submit' [<submit options>] [<master branch name>] + + +DESCRIPTION +----------- +This command provides a way to interact with p4 repositories +using git. + +Create a new git repository from an existing p4 repository using +'git p4 clone', giving it one or more p4 depot paths. Incorporate +new commits from p4 changes with 'git p4 sync'. The 'sync' command +is also used to include new branches from other p4 depot paths. +Submit git changes back to p4 using 'git p4 submit'. The command +'git p4 rebase' does a sync plus rebases the current branch onto +the updated p4 remote branch. + + +EXAMPLE +------- +* Create an alias for 'git p4', using the full path to the 'git-p4' + script if needed: ++ +------------ +$ git config --global alias.p4 '!git-p4' +------------ + +* Clone a repository: ++ +------------ +$ git p4 clone //depot/path/project +------------ + +* Do some work in the newly created git repository: ++ +------------ +$ cd project +$ vi foo.h +$ git commit -a -m "edited foo.h" +------------ + +* Update the git repository with recent changes from p4, rebasing your + work on top: ++ +------------ +$ git p4 rebase +------------ + +* Submit your commits back to p4: ++ +------------ +$ git p4 submit +------------ + + +COMMANDS +-------- + +Clone +~~~~~ +Generally, 'git p4 clone' is used to create a new git directory +from an existing p4 repository: +------------ +$ git p4 clone //depot/path/project +------------ +This: + +1. Creates an empty git repository in a subdirectory called 'project'. ++ +2. Imports the full contents of the head revision from the given p4 +depot path into a single commit in the git branch 'refs/remotes/p4/master'. ++ +3. Creates a local branch, 'master' from this remote and checks it out. + +To reproduce the entire p4 history in git, use the '@all' modifier on +the depot path: +------------ +$ git p4 clone //depot/path/project@all +------------ + + +Sync +~~~~ +As development continues in the p4 repository, those changes can +be included in the git repository using: +------------ +$ git p4 sync +------------ +This command finds new changes in p4 and imports them as git commits. + +P4 repositories can be added to an existing git repository using +'git p4 sync' too: +------------ +$ mkdir repo-git +$ cd repo-git +$ git init +$ git p4 sync //path/in/your/perforce/depot +------------ +This imports the specified depot into +'refs/remotes/p4/master' in an existing git repository. The +'--branch' option can be used to specify a different branch to +be used for the p4 content. + +If a git repository includes branches 'refs/remotes/origin/p4', these +will be fetched and consulted first during a 'git p4 sync'. Since +importing directly from p4 is considerably slower than pulling changes +from a git remote, this can be useful in a multi-developer environment. + + +Rebase +~~~~~~ +A common working pattern is to fetch the latest changes from the p4 depot +and merge them with local uncommitted changes. Often, the p4 repository +is the ultimate location for all code, thus a rebase workflow makes +sense. This command does 'git p4 sync' followed by 'git rebase' to move +local commits on top of updated p4 changes. +------------ +$ git p4 rebase +------------ + + +Submit +~~~~~~ +Submitting changes from a git repository back to the p4 repository +requires a separate p4 client workspace. This should be specified +using the 'P4CLIENT' environment variable or the git configuration +variable 'git-p4.client'. The p4 client must exist, but the client root +will be created and populated if it does not already exist. + +To submit all changes that are in the current git branch but not in +the 'p4/master' branch, use: +------------ +$ git p4 submit +------------ + +To specify a branch other than the current one, use: +------------ +$ git p4 submit topicbranch +------------ + +The upstream reference is generally 'refs/remotes/p4/master', but can +be overridden using the '--origin=' command-line option. + +The p4 changes will be created as the user invoking 'git p4 submit'. The +'--preserve-user' option will cause ownership to be modified +according to the author of the git commit. This option requires admin +privileges in p4, which can be granted using 'p4 protect'. + + +OPTIONS +------- + +General options +~~~~~~~~~~~~~~~ +All commands except clone accept this option. + +--git-dir <dir>:: + Set the 'GIT_DIR' environment variable. See linkgit:git[1]. + +Sync options +~~~~~~~~~~~~ +These options can be used in the initial 'clone' as well as in +subsequent 'sync' operations. + +--branch <branch>:: + Import changes into given branch. If the branch starts with + 'refs/', it will be used as is, otherwise the path 'refs/heads/' + will be prepended. The default branch is 'master'. If used + with an initial clone, no HEAD will be checked out. ++ +This example imports a new remote "p4/proj2" into an existing +git repository: +---- + $ git init + $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 +---- + +--detect-branches:: + Use the branch detection algorithm to find new paths in p4. It is + documented below in "BRANCH DETECTION". + +--changesfile <file>:: + Import exactly the p4 change numbers listed in 'file', one per + line. Normally, 'git p4' inspects the current p4 repository + state and detects the changes it should import. + +--silent:: + Do not print any progress information. + +--verbose:: + Provide more progress information. + +--detect-labels:: + Query p4 for labels associated with the depot paths, and add + them as tags in git. + +--import-local:: + By default, p4 branches are stored in 'refs/remotes/p4/', + where they will be treated as remote-tracking branches by + linkgit:git-branch[1] and other commands. This option instead + puts p4 branches in 'refs/heads/p4/'. Note that future + sync operations must specify '--import-local' as well so that + they can find the p4 branches in refs/heads. + +--max-changes <n>:: + Limit the number of imported changes to 'n'. Useful to + limit the amount of history when using the '@all' p4 revision + specifier. + +--keep-path:: + The mapping of file names from the p4 depot path to git, by + default, involves removing the entire depot path. With this + option, the full p4 depot path is retained in git. For example, + path '//depot/main/foo/bar.c', when imported from + '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + git path is instead 'depot/main/foo/bar.c'. + +--use-client-spec:: + Use a client spec to find the list of interesting files in p4. + See the "CLIENT SPEC" section below. + +Clone options +~~~~~~~~~~~~~ +These options can be used in an initial 'clone', along with the 'sync' +options described above. + +--destination <directory>:: + Where to create the git repository. If not provided, the last + component in the p4 depot path is used to create a new + directory. + +--bare:: + Perform a bare clone. See linkgit:git-clone[1]. + +-/ <path>:: + Exclude selected depot paths when cloning. + +Submit options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 submit' behavior. + +--verbose:: + Provide more progress information. + +--origin <commit>:: + Upstream location from which commits are identified to submit to + p4. By default, this is the most recent p4 commit reachable + from 'HEAD'. + +-M[<n>]:: + Detect renames. See linkgit:git-diff[1]. Renames will be + represented in p4 using explicit 'move' operations. There + is no corresponding option to detect copies, but there are + variables for both moves and copies. + +--preserve-user:: + Re-author p4 changes before submitting to p4. This option + requires p4 admin privileges. + + +DEPOT PATH SYNTAX +----------------- +The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can +be one or more space-separated p4 depot paths, with an optional +p4 revision specifier on the end: + +"//depot/my/project":: + Import one commit with all files in the '#head' change under that tree. + +"//depot/my/project@all":: + Import one commit for each change in the history of that depot path. + +"//depot/my/project@1,6":: + Import only changes 1 through 6. + +"//depot/proj1@all //depot/proj2@all":: + Import all changes from both named depot paths into a single + repository. Only files below these directories are included. + There is not a subdirectory in git for each "proj1" and "proj2". + You must use the '--destination' option when specifying more + than one depot path. The revision specifier must be specified + identically on each depot path. If there are files in the + depot paths with the same name, the path with the most recently + updated version of the file is the one that appears in git. + +See 'p4 help revisions' for the full syntax of p4 revision specifiers. + + +CLIENT SPEC +----------- +The p4 client specification is maintained with the 'p4 client' command +and contains among other fields, a View that specifies how the depot +is mapped into the client repository. Git-p4 can consult the client +spec when given the '--use-client-spec' option or useClientSpec +variable. + +The full syntax for a p4 view is documented in 'p4 help views'. Git-p4 +knows only a subset of the view syntax. It understands multi-line +mappings, overlays with '+', exclusions with '-' and double-quotes +around whitespace. Of the possible wildcards, git-p4 only handles +'...', and only when it is at the end of the path. Git-p4 will complain +if it encounters an unhandled wildcard. + +Bugs in the implementation of overlap mappings exist. If multiple depot +paths map through overlays to the same location in the repository, +git-p4 can choose the wrong one. This is hard to solve without +dedicating a client spec just for git-p4. + +The name of the client can be given to git-p4 in multiple ways. The +variable 'git-p4.client' takes precedence if it exists. Otherwise, +normal p4 mechanisms of determining the client are used: environment +variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. + + +BRANCH DETECTION +---------------- +P4 does not have the same concept of a branch as git. Instead, +p4 organizes its content as a directory tree, where by convention +different logical branches are in different locations in the tree. +The 'p4 branch' command is used to maintain mappings between +different areas in the tree, and indicate related content. 'git p4' +can use these mappings to determine branch relationships. + +If you have a repository where all the branches of interest exist as +subdirectories of a single depot path, you ca |