This comes on top of the ispell'ed one to correct technical
details:
* We made describe output to be a valid object name some time ago.
* With recent addition to take directory names and path patterns,
it is not limited to "small number of files" case anymore.
* The original about separate-remote was full of half sentences
so I stitched them together to make them make some sense.
* Sorry, I recently applied the same "fix" as Cogito got quite
some time ago, and both lightweight and annotated tags are
now followed upon a tracking fetch.
* rsync has been deprecated for quite some time.
* The official party line for git-native-over-ssh is host:path
* Octopus should be discouraged unless talking about truly
trivial merges. Explain its downside better.
* Amend is a lot handier than --no-commit, as you do not have to
plan ahead. We should encourage "Pull/merge normally and if
the result is not what you like, amend it" workflow.
--- a/doc
+++ b/doc
@@ -278,11 +278,14 @@
Third is git-describe. This is something like git-name-rev, but
backwards: it finds the closest reference that is an ancestor of the
-specified commit. Its output is not acceptable git input, but takes
-the form of either
+specified commit. It takes the form of either
+
v1.2 (tag name), or
v1.2-g12345678 (commit 12345678, whose nearest ancestor is v1.2)
+and it is accepted as an input if the abbreviated object name that follows
+"tagname-g" prefix is unambiguous.
+
git-describe's output is intended to be used as a software version
number, something like the "rcsid" feature in RCS and CVS.
By default, git-describe uses only heavyweight tags for its naming,
@@ -345,13 +348,14 @@
in the working directory. This option can be used with no <branch>
specified (defaults to HEAD) to undo local edits.
-2) Revert changes to a small number of files.
+2) Revert changes to the files in the working tree.
git checkout [<revision>] [--] <paths>
will copy the version of the <paths> from the index to the working
directory. If a <revision> is given, the index for those paths will
be updated from the given revision before copying from the index to
- the working tree.
+ the working tree. <paths> can name directories, and/or contain
+ glob patterns to revert many files.
Unlike the version with no <paths> specified, this does NOT change
HEAD, even if <paths> is ".".
@@ -782,18 +786,12 @@
default in future), that places copies of the remote servers' heads
under .git/refs/remotes/<server>/<branch>.
-Then you can refer to
-
-If you use "git-line --use-separate-remote", it will set
-
-If you want to use the "separate remotes" tracking branch
-There's an alternate way, using the --use-separate-remote option
-to git-clone. This sets up a copy of the remote server's heads
-under .git/refs/remotes/origin/<name>. Then you can refer to
-"origin/<branch>" whenever you want.
+If you use "git-clone --use-separate-remote", it sets up a copy of
+the remote server's heads under .git/refs/remotes/origin/<name>.
+Then you can refer to "origin/<branch>" whenever you want.
Because the branch names are got under .git/refs/heads, the git
-tools will not let you commit to the branch.
+tools will not let you commit to the remote branchbranch.
* Remotes files
@@ -877,7 +875,7 @@
* Remote tags
When you fetch to a tracking branch, git-fetch also fetches every
-heavyweight tag (one that involves an actual tag object) that
+tag under .git/refs/tags/ in the remote repository that
points to a commit reachable from the branch head and installs a
copy locally.
@@ -913,11 +911,19 @@
http clients also need some extra index information to help them
find which pack files they need. git-update-server-info is the
- command that generates these files, but it's run automatically
- from git-repack, so it's not too important to know.
+ command that generates these files, and it is important to keep
+ them up-to-date. A recommended practice is to have this command in
+ .git/hooks/update so that every time you push into the repository
+ they are automatically updated. You can enable the hook (which
+ is installed when the repository is initialized) with "chmod +x".
+
+ In addition to http://, https:// and ftp:// URL are allowed and
+ handled by the same backend that uses cURL library.
2) rsync protocol. This is basically an alternative to http, and
- has the same strictures and limitations.
+ has the same strictures and limitations. This is deprecated and
+ its use has been discouraged for quite some time, although it still
+ works.
3) The git protocol. This is represented with a git:// URL, and talks
to a dedicated git daemon (see the git-daemon man page) on the
@@ -929,8 +935,9 @@
require any special care when repacking. git-daemon is purposefully
written to provide read-only service.
-4) The git protocol over ssh. This is a git+ssh:// URL; ssh:// is
- accepted as a synonym. It has the same efficiency issues as
+4) The git protocol over ssh. This is spelled as "host:path" like scp
+ command, and ssh:// URL and git+ssh:// are
+ accepted as synonyms. It has the same efficiency issues as
plain git. If you want to limit ssh users to just the git commands
necessary to share work, git provides a git-shell command that can
be used as a very limited login shell.
@@ -1046,7 +1053,7 @@
Now, you can also specify a remote repository to merge from, using a
-git://, http:// or git+ssh:// URL. This is what Linus does all day
+git:// or http:// URLs or host:path syntax. This is what Linus does all day
long, and why the git-pull tool is optimized to allow that. It uses
git-fetch to fetch the remote branch without assigning it a branch name
(as mentioned above, it gets the magic name FETCH_HEAD), and them merges
@@ -1213,15 +1220,15 @@
what's already there, enter "5401f304" instead, and click "Goto".)
The octopus strategy is invoked automatically when you specify more
-than one branch at a time to merge in with "git pull". It can't handle
-complicated overlaps and file renames as well as the 2-way recursive
+than one branch at a time to merge in with "git pull". It refuses to
+handle complicated overlaps and file renames as well as the 2-way recursive
strategy, but if you have a number of simple, independent changes that you
want to merge together, an octopus merge is the obvious way to document
the fact that they're truly independent.
-The only downside to using an octopus to combine a number of simple
-changes is that any merge makes git-bisect's job harder. If you have
-a development history like
+A major downside to using an octopus to combine a number of
+changes is that an octopus merge makes git-bisect's job harder.
+If you have a development history like
/-b-\
/ \
@@ -1234,9 +1241,15 @@
\-f-/
And you know that a works but g doesn't, there's no way to do a binary
-search on b through f; they have to be searched linearly. This is
-no harder to bisect, and a lot nicer-looking than the equivalent with
-2-way merges:
+search on b through f; they have to be searched linearly. In
+addition, a merge tends to become more error prone as it has more
+parents. Your bisect could show that all of b, c, d, e, f are good
+and the error is in a mismerge at g. This is why the octopus strategy
+refuses to do anything other than a very simple merge.
+
+Although an octopus is somewhat nicer-looking than the equivalent with
+a series of 2-parent merges, the latter is a lot more efficient to
+bisect:
/-b
/ \
@@ -1248,7 +1261,12 @@
\ /
\-f-----/
-But if they were just done one after the other, you'd have
+With this structure, if bisecting at h proves that it was Ok,
+then you do not have to check b, c, d, g (the error must be in e, f
+or mismerge at i or j).
+
+Even simpler to bisect is if they were just done one after the other.
+In such a case, you'd have:
--a--b--c--d--e--f--
@@ -1410,6 +1428,9 @@
In many cases, this is fine, and you can save it and complete the
commit. Or you can add something about the merge if it needs saying.
+If the merge was complex, it will turn out to be useful to describe
+how you choose to resolve conflicts, and that is the primary reason
+the boilerplate lists conflicted files.
When I'm done, if I don't need branch A any more, I can
@@ -1763,11 +1784,11 @@
the changelog. It could have been a separate commit, but didn't seem
worth it.
-This was done by forcing the git-pull to not commit:
+This was done by amending the merge commit.
- git pull --no-commit . <branch>
+ git pull . <branch>
(edit as desired)
- git commit
+ git commit --amend -a
The commit message should be edited to explain that this is not just
a normal merge, as was done in this case.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html