From 5162e69732d13dd079919a389a6ace8878aad716 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sat, 29 Dec 2007 00:20:38 -0600 Subject: Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P\w(\w|-)*?):(?P\S*?)(\[(?P.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P(http|https|ftp|file|mailto|callto|image|link)):(?P\S*?)(\[(?P.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 74c5478ba1..8421d1fd78 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -15,7 +15,7 @@ DESCRIPTION ----------- Reads the tree information given by into the index, but does not actually *update* any of the files it "caches". (see: -gitlink:git-checkout-index[1]) +linkgit:git-checkout-index[1]) Optionally, it can merge a tree into the index, perform a fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` @@ -347,8 +347,8 @@ have finished your work-in-progress), attempt the merge again. See Also -------- -gitlink:git-write-tree[1]; gitlink:git-ls-files[1]; -gitlink:gitignore[5] +linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; +linkgit:gitignore[5] Author @@ -361,4 +361,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list Date: Wed, 28 May 2008 16:55:27 -0700 Subject: Manual subsection to refer to other pages is SEE ALSO Consistently say so in all caps as it is customary to do so. Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 8421d1fd78..2e097a140c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -345,7 +345,7 @@ middle of doing, and when your working tree is ready (i.e. you have finished your work-in-progress), attempt the merge again. -See Also +SEE ALSO -------- linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; linkgit:gitignore[5] -- cgit v1.2.3 From 9e1f0a85c68323830ea117092c55192b17aa3ac8 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Fri, 6 Jun 2008 09:07:32 +0200 Subject: documentation: move git(7) to git(1) As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 2e097a140c..cbe68352bf 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -361,4 +361,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list Date: Mon, 9 Jun 2008 22:25:15 +0200 Subject: git-read-tree: document -v option. Signed-off-by: Miklos Vajna Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 8421d1fd78..c95ad9f145 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -50,6 +50,9 @@ OPTIONS trees that are not directly related to the current working tree status into a temporary index file. +-v:: + Show the progress of checking files out. + --trivial:: Restrict three-way merge by `git-read-tree` to happen only if there is no file-level merging required, instead -- cgit v1.2.3 From b1889c36d85514e5e70462294c561a02c2edfe2b Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 01:09:04 -0500 Subject: Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command " in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 58fb906ef6..1a57f58071 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' ( | [[-m [--trivial] [--aggressive] | --reset | --prefix=] [-u | -i]] [--exclude-per-directory=] [--index-output=] [ []]) +'git read-tree' ( | [[-m [--trivial] [--aggressive] | --reset | --prefix=] [-u | -i]] [--exclude-per-directory=] [--index-output=] [ []]) DESCRIPTION @@ -127,8 +127,8 @@ given pathname, and the contents of the path matches with the tree being read, the stat info from the index is used. (In other words, the index's stat()s take precedence over the merged tree's). -That means that if you do a `git-read-tree -m ` followed by a -`git-checkout-index -f -u -a`, the `git-checkout-index` only checks out +That means that if you do a `git read-tree -m ` followed by a +`git checkout-index -f -u -a`, the `git-checkout-index` only checks out the stuff that really changed. This is used to avoid unnecessary false hits when `git-diff-files` is @@ -138,7 +138,7 @@ run after `git-read-tree`. Two Tree Merge ~~~~~~~~~~~~~~ -Typically, this is invoked as `git-read-tree -m $H $M`, where $H +Typically, this is invoked as `git read-tree -m $H $M`, where $H is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast forward situation). @@ -151,7 +151,7 @@ the following: 2. The user wants to fast-forward to $M. -In this case, the `git-read-tree -m $H $M` command makes sure +In this case, the `git read-tree -m $H $M` command makes sure that no local change is lost as the result of this "merge". Here are the "carry forward" rules: @@ -198,13 +198,13 @@ operating under the -u flag. When this form of git-read-tree returns successfully, you can see what "local changes" you made are carried forward by running -`git-diff-index --cached $M`. Note that this does not -necessarily match `git-diff-index --cached $H` would have +`git diff-index --cached $M`. Note that this does not +necessarily match `git diff-index --cached $H` would have produced before such a two tree merge. This is because of cases 18 and 19 --- if you already had the changes in $M (e.g. maybe -you picked it up via e-mail in a patch form), `git-diff-index +you picked it up via e-mail in a patch form), `git diff-index --cached $H` would have told you about the change before this -merge, but it would not show in `git-diff-index --cached $M` +merge, but it would not show in `git diff-index --cached $M` output after two-tree merge. @@ -219,7 +219,7 @@ starts out at 1. This means that you can do ---------------- -$ git-read-tree -m +$ git read-tree -m ---------------- and you will end up with an index with all of the entries in @@ -304,8 +304,8 @@ commit. To illustrate, suppose you start from what has been committed last to your repository: ---------------- -$ JC=`git-rev-parse --verify "HEAD^0"` -$ git-checkout-index -f -u -a $JC +$ JC=`git rev-parse --verify "HEAD^0"` +$ git checkout-index -f -u -a $JC ---------------- You do random edits, without running git-update-index. And then @@ -313,7 +313,7 @@ you notice that the tip of your "upstream" tree has advanced since you pulled from him: ---------------- -$ git-fetch git://.... linus +$ git fetch git://.... linus $ LT=`cat .git/FETCH_HEAD` ---------------- @@ -323,10 +323,10 @@ added or modified index entries since $JC, and if you haven't, then does the right thing. So with the following sequence: ---------------- -$ git-read-tree -m -u `git-merge-base $JC $LT` $JC $LT -$ git-merge-index git-merge-one-file -a +$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT +$ git merge-index git-merge-one-file -a $ echo "Merge with Linus" | \ - git-commit-tree `git-write-tree` -p $JC -p $LT + git commit-tree `git write-tree` -p $JC -p $LT ---------------- what you would commit is a pure merge between $JC and $LT without -- cgit v1.2.3 From 483bc4f045881b998512ae814d6cf44d0c0cb493 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 13:56:34 -0500 Subject: Documentation formatting and cleanup Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 1a57f58071..0c7cc6b940 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -121,7 +121,7 @@ provided. Single Tree Merge ~~~~~~~~~~~~~~~~~ -If only 1 tree is specified, git-read-tree operates as if the user did not +If only 1 tree is specified, `git-read-tree` operates as if the user did not specify `-m`, except that if the original index has an entry for a given pathname, and the contents of the path matches with the tree being read, the stat info from the index is used. (In other words, the @@ -143,7 +143,7 @@ is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast forward situation). -When two trees are specified, the user is telling git-read-tree +When two trees are specified, the user is telling `git-read-tree` the following: 1. The current index and work tree is derived from $H, but @@ -193,10 +193,10 @@ Here are the "carry forward" rules: In all "keep index" cases, the index entry stays as in the original index file. If the entry were not up to date, -git-read-tree keeps the copy in the work tree intact when +`git-read-tree` keeps the copy in the work tree intact when operating under the -u flag. -When this form of git-read-tree returns successfully, you can +When this form of `git-read-tree` returns successfully, you can see what "local changes" you made are carried forward by running `git diff-index --cached $M`. Note that this does not necessarily match `git diff-index --cached $H` would have @@ -261,7 +261,7 @@ start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: - if a file exists in identical format in all three trees, it will - automatically collapse to "merged" state by git-read-tree. + automatically collapse to "merged" state by `git-read-tree`. - a file that has _any_ difference what-so-ever in the three trees will stay as separate entries in the index. It's up to "porcelain @@ -308,7 +308,7 @@ $ JC=`git rev-parse --verify "HEAD^0"` $ git checkout-index -f -u -a $JC ---------------- -You do random edits, without running git-update-index. And then +You do random edits, without running `git-update-index`. And then you notice that the tip of your "upstream" tree has advanced since you pulled from him: @@ -334,7 +334,7 @@ your work-in-progress changes, and your work tree would be updated to the result of the merge. However, if you have local changes in the working tree that -would be overwritten by this merge,`git-read-tree` will refuse +would be overwritten by this merge, `git-read-tree` will refuse to run to prevent your changes from being lost. In other words, there is no need to worry about what exists only -- cgit v1.2.3 From ba020ef5eb5fca3d757bd580ff117adaf81ca079 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 3 Jul 2008 00:41:41 -0500 Subject: manpages: italicize git command names (which were in teletype font) The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 42 ++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 0c7cc6b940..6f4b9b017f 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -22,8 +22,8 @@ fast-forward (i.e. 2-way) merge, or a 3-way merge, with the `-m` flag. When used with `-m`, the `-u` flag causes it to also update the files in the work tree with the result of the merge. -Trivial merges are done by `git-read-tree` itself. Only conflicting paths -will be in unmerged state when `git-read-tree` returns. +Trivial merges are done by 'git-read-tree' itself. Only conflicting paths +will be in unmerged state when 'git-read-tree' returns. OPTIONS ------- @@ -54,13 +54,13 @@ OPTIONS Show the progress of checking files out. --trivial:: - Restrict three-way merge by `git-read-tree` to happen + Restrict three-way merge by 'git-read-tree' to happen only if there is no file-level merging required, instead of resolving merge for trivial cases and leaving conflicting files unresolved in the index. --aggressive:: - Usually a three-way merge by `git-read-tree` resolves + Usually a three-way merge by 'git-read-tree' resolves the merge for really trivial cases and leaves other cases unresolved in the index, so that Porcelains can implement different merge policies. This flag makes the @@ -113,7 +113,7 @@ OPTIONS Merging ------- -If `-m` is specified, `git-read-tree` can perform 3 kinds of +If `-m` is specified, 'git-read-tree' can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a fast-forward merge with 2 trees, or a 3-way merge if 3 trees are provided. @@ -121,18 +121,18 @@ provided. Single Tree Merge ~~~~~~~~~~~~~~~~~ -If only 1 tree is specified, `git-read-tree` operates as if the user did not +If only 1 tree is specified, 'git-read-tree' operates as if the user did not specify `-m`, except that if the original index has an entry for a given pathname, and the contents of the path matches with the tree being read, the stat info from the index is used. (In other words, the index's stat()s take precedence over the merged tree's). That means that if you do a `git read-tree -m ` followed by a -`git checkout-index -f -u -a`, the `git-checkout-index` only checks out +`git checkout-index -f -u -a`, the 'git-checkout-index' only checks out the stuff that really changed. -This is used to avoid unnecessary false hits when `git-diff-files` is -run after `git-read-tree`. +This is used to avoid unnecessary false hits when 'git-diff-files' is +run after 'git-read-tree'. Two Tree Merge @@ -143,7 +143,7 @@ is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast forward situation). -When two trees are specified, the user is telling `git-read-tree` +When two trees are specified, the user is telling 'git-read-tree' the following: 1. The current index and work tree is derived from $H, but @@ -193,10 +193,10 @@ Here are the "carry forward" rules: In all "keep index" cases, the index entry stays as in the original index file. If the entry were not up to date, -`git-read-tree` keeps the copy in the work tree intact when +'git-read-tree' keeps the copy in the work tree intact when operating under the -u flag. -When this form of `git-read-tree` returns successfully, you can +When this form of 'git-read-tree' returns successfully, you can see what "local changes" you made are carried forward by running `git diff-index --cached $M`. Note that this does not necessarily match `git diff-index --cached $H` would have @@ -213,7 +213,7 @@ output after two-tree merge. Each "index" entry has two bits worth of "stage" state. stage 0 is the normal one, and is the only one you'd see in any kind of normal use. -However, when you do `git-read-tree` with three trees, the "stage" +However, when you do 'git-read-tree' with three trees, the "stage" starts out at 1. This means that you can do @@ -229,7 +229,7 @@ branch into the current branch, we use the common ancestor tree as , the current branch head as , and the other branch head as . -Furthermore, `git-read-tree` has special-case logic that says: if you see +Furthermore, 'git-read-tree' has special-case logic that says: if you see a file that matches in all respects in the following states, it "collapses" back to "stage0": @@ -245,7 +245,7 @@ a file that matches in all respects in the following states, it - stage 1 and stage 3 are the same and stage 2 is different take stage 2 (we did something while they did nothing) -The `git-write-tree` command refuses to write a nonsensical tree, and it +The 'git-write-tree' command refuses to write a nonsensical tree, and it will complain about unmerged entries if it sees a single entry that is not stage 0. @@ -261,7 +261,7 @@ start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: - if a file exists in identical format in all three trees, it will - automatically collapse to "merged" state by `git-read-tree`. + automatically collapse to "merged" state by 'git-read-tree'. - a file that has _any_ difference what-so-ever in the three trees will stay as separate entries in the index. It's up to "porcelain @@ -285,8 +285,8 @@ populated. Here is an outline of how the algorithm works: matching "stage1" entry if it exists too. .. all the normal trivial rules .. -You would normally use `git-merge-index` with supplied -`git-merge-one-file` to do this last step. The script updates +You would normally use 'git-merge-index' with supplied +'git-merge-one-file' to do this last step. The script updates the files in the working tree as it merges each path and at the end of a successful merge. @@ -308,7 +308,7 @@ $ JC=`git rev-parse --verify "HEAD^0"` $ git checkout-index -f -u -a $JC ---------------- -You do random edits, without running `git-update-index`. And then +You do random edits, without running 'git-update-index'. And then you notice that the tip of your "upstream" tree has advanced since you pulled from him: @@ -334,14 +334,14 @@ your work-in-progress changes, and your work tree would be updated to the result of the merge. However, if you have local changes in the working tree that -would be overwritten by this merge, `git-read-tree` will refuse +would be overwritten by this merge, 'git-read-tree' will refuse to run to prevent your changes from being lost. In other words, there is no need to worry about what exists only in the working tree. When you have local changes in a part of the project that is not involved in the merge, your changes do not interfere with the merge, and are kept intact. When they -*do* interfere, the merge does not even start (`git-read-tree` +*do* interfere, the merge does not even start ('git-read-tree' complains loudly and fails without modifying anything). In such a case, you can simply continue doing what you were in the middle of doing, and when your working tree is ready (i.e. you -- cgit v1.2.3 From 5521883490e85f4d973141972cf16f89a79f1979 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 7 Sep 2008 19:49:25 -0700 Subject: checkout: do not lose staged removal The logic to checkout a different commit implements the safety to never lose user's local changes. For example, switching from a commit to another commit, when you have changed a path that is different between them, need to merge your changes to the version from the switched-to commit, which you may not necessarily be able to resolve easily. By default, "git checkout" refused to switch branches, to give you a chance to stash your local changes (or use "-m" to merge, accepting the risks of getting conflicts). This safety, however, had one deliberate hole since early June 2005. When your local change was to remove a path (and optionally to stage that removal), the command checked out the path from the switched-to commit nevertheless. This was to allow an initial checkout to happen smoothly (e.g. an initial checkout is done by starting with an empty index and switching from the commit at the HEAD to the same commit). We can tighten the rule slightly to allow this special case to pass, without losing sight of removal explicitly done by the user, by noticing if the index is truly empty when the operation begins. For historical background, see: http://thread.gmane.org/gmane.comp.version-control.git/4641/focus=4646 This case is marked as *0* in the message, which both Linus and I said "it feels somewhat wrong but otherwise we cannot start from an empty index". Signed-off-by: Junio C Hamano --- Documentation/git-read-tree.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 6f4b9b017f..309deac23b 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -160,7 +160,10 @@ Here are the "carry forward" rules: 0 nothing nothing nothing (does not happen) 1 nothing nothing exists use M 2 nothing exists nothing remove path from index - 3 nothing exists exists use M + 3 nothing exists exists, use M if "initial checkout" + H == M keep index otherwise + exists fail + H != M clean I==H I==M ------------------ @@ -207,6 +210,12 @@ you picked it up via e-mail in a patch form), `git diff-index merge, but it would not show in `git diff-index --cached $M` output after two-tree merge. +Case #3 is slightly tricky and needs explanation. The result from this +rule logically should be to remove the path if the user staged the removal +of the path and then swiching to a new branch. That however will prevent +the initial checkout from happening, so the rule is modified to use M (new +tree) only when the contents of the index is empty. Otherwise the removal +of the path is kept as long as $H and $M are the same. 3-Way Merge ~~~~~~~~~~~ -- cgit v1.2.3 From 79fd4cc749826dd78c6ab3cd225bdb5c92db2de8 Mon Sep 17 00:00:00 2001 From: Ralf Wildenhues Date: Mon, 29 Sep 2008 22:30:00 +0200 Subject: Correct typos in RelNotes-1.6.1 Signed-off-by: Shawn O. Pearce --- Documentation/git-read-tree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-read-tree.txt') diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 309deac23b..7160fa1536 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -212,7 +212,7 @@ output after two-tree merge. Case #3 is slightly tricky and needs explanation. The result from this rule logically should be to remove the path if the user staged the removal -of the path and then swiching to a new branch. That however will prevent +of the path and then switching to a new branch. That however will prevent the initial checkout from happening, so the rule is modified to use M (new tree) only when the contents of the index is empty. Otherwise the removal of the path is kept as long as $H and $M are the same. -- cgit v1.2.3