X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fuser-manual.txt;h=03736bbcd3ebfd5e1cbe6a006acb2b31411af527;hb=50cfde14531a5b354bbc3a070fe39c1ee86e2915;hp=b4980a2a0da96c8653745f7bdb2afe7c1d0df9f6;hpb=9a241220fd19c93a89501bfef51ce4ec79a79033;p=git.git diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index b4980a2a0..03736bbcd 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -398,7 +398,7 @@ branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for example in email), then you are guaranteed that name will refer to the same commit in their repository -that you it does in yours (assuming their repository has that commit at +that it does in yours (assuming their repository has that commit at all). Understanding history: commits, parents, and reachability @@ -425,8 +425,8 @@ if commit X is an ancestor of commit Y. Equivalently, you could say that Y is a descendent of X, or that there is a chain of parents leading from commit Y to commit X. -Undestanding history: History diagrams -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Understanding history: History diagrams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We will sometimes represent git history using diagrams like the one below. Commits are shown as "o", and the links between them with @@ -617,7 +617,7 @@ the relationships between these snapshots. Git provides extremely flexible and fast tools for exploring the history of a project. -We start with one specialized tool which is useful for finding the +We start with one specialized tool that is useful for finding the commit that introduced a bug into a project. How to use bisect to find a regression @@ -692,7 +692,7 @@ Naming commits We have seen several ways of naming commits already: - - 40-hexdigit SHA1 id + - 40-hexdigit object name - branch name: refers to the commit at the head of the given branch - tag name: refers to the commit pointed to by the given tag @@ -705,7 +705,7 @@ gitlink:git-rev-parse[1] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- -$ git show fb47ddb2 # the first few characters of the SHA1 id +$ git show fb47ddb2 # the first few characters of the object name # are usually enough to specify it uniquely $ git show HEAD^ # the parent of the HEAD commit $ git show HEAD^^ # the grandparent @@ -743,8 +743,8 @@ which refers to the other branch that we're merging in to the current branch. The gitlink:git-rev-parse[1] command is a low-level command that is -occasionally useful for translating some name for a commit to the SHA1 id for -that commit: +occasionally useful for translating some name for a commit to the object +name for that commit: ------------------------------------------------- $ git rev-parse origin @@ -806,7 +806,7 @@ display options. Note that git log starts with the most recent commit and works backwards through the parents; however, since git history can contain -multiple independant lines of development, the particular order that +multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary. Generating diffs @@ -861,7 +861,7 @@ $ git diff origin..master will tell you whether the contents of the project are the same at the two branches; in theory, however, it's possible that the same project contents could have been arrived at by two different historical -routes. You could compare the SHA1 id's: +routes. You could compare the object names: ------------------------------------------------- $ git rev-list origin @@ -933,12 +933,38 @@ actually is an ancestor of v1.5.0-rc1. Alternatively, note that ------------------------------------------------- -$ git log v1.5.0-rc1..305db0fd +$ git log v1.5.0-rc1..e05db0fd ------------------------------------------------- -will produce empty output if and only if v1.5.0-rc1 includes 305db0fd, +will produce empty output if and only if v1.5.0-rc1 includes e05db0fd, because it outputs only commits that are not reachable from v1.5.0-rc1. +As yet another alternative, the gitlink:git-show-branch[1] command lists +the commits reachable from its arguments with a display on the left-hand +side that indicates which arguments that commit is reachable from. So, +you can run something like + +------------------------------------------------- +$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 +! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if +available + ! [v1.5.0-rc0] GIT v1.5.0 preview + ! [v1.5.0-rc1] GIT v1.5.0-rc1 + ! [v1.5.0-rc2] GIT v1.5.0-rc2 +... +------------------------------------------------- + +then search for a line that looks like + +------------------------------------------------- ++ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if +available +------------------------------------------------- + +Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and +from v1.5.0-rc2, but not from v1.5.0-rc0. + + Developing with git =================== @@ -1049,7 +1075,7 @@ $ git commit ------------------------------------------------- and git will prompt you for a commit message and then create the new -commmit. Check to make sure it looks like what you expected with +commit. Check to make sure it looks like what you expected with ------------------------------------------------- $ git show @@ -1439,7 +1465,7 @@ $ gitk master@{"1 week ago"} # ... or last week ------------------------------------------------- The reflogs are kept by default for 30 days, after which they may be -pruned. See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn +pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn how to control this pruning, and see the "SPECIFYING REVISIONS" section of gitlink:git-rev-parse[1] for details. @@ -1466,7 +1492,7 @@ dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5 ... ------------------------------------------------- -and watch for output that mentions "dangling commits". You can examine +You can examine one of those dangling commits with, for example, ------------------------------------------------ @@ -1554,7 +1580,7 @@ Submitting patches to a project If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: -First, use gitlink:git-format-patches[1]; for example: +First, use gitlink:git-format-patch[1]; for example: ------------------------------------------------- $ git format-patch origin @@ -1776,7 +1802,9 @@ set this up. Allow web browsing of a repository ---------------------------------- -TODO: Brief setup-instructions for gitweb +The gitweb cgi script provides users an easy way to browse your +project's files and history without having to install git; see the file +gitweb/README in the git source tree for instructions on setting it up. Examples -------- @@ -2727,7 +2755,7 @@ stages to temporary files and calls a "merge" script on it: $ git-merge-index git-merge-one-file hello.c ------------------------------------------------- -and that is what higher level `git resolve` is implemented with. +and that is what higher level `git merge -s resolve` is implemented with. How git stores objects efficiently: pack files ---------------------------------------------- @@ -2895,11 +2923,13 @@ Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. +Say something about .gitignore. + Scan Documentation/ for other stuff left out; in particular: howto's some of technical/? hooks - etc. + list of commands in gitlink:git[1] Scan email archives for other stuff left out @@ -2923,6 +2953,9 @@ Include cross-references to the glossary, where appropriate. Document shallow clones? See draft 1.5.0 release notes for some documentation. -Add a sectin on working with other version control systems, including +Add a section on working with other version control systems, including CVS, Subversion, and just imports of series of release tarballs. +More details on gitweb? + +Write a chapter on using plumbing and writing scripts.