From: Junio C Hamano Date: Wed, 20 Jan 2016 19:43:27 +0000 (-0800) Subject: Merge branch 'ss/user-manual' X-Git-Tag: v2.8.0-rc0~117 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/7e3e80a88181c99d33567c05fc865e26f971e954?hp=-c Merge branch 'ss/user-manual' Drop a few old "todo" items by deciding that the change one of them suggests is not such a good idea, and doing the change the other one suggested to do. * ss/user-manual: user-manual: add addition gitweb information user-manual: add section documenting shallow clones glossary: define the term shallow clone user-manual: remove temporary branch entry from todo list --- 7e3e80a88181c99d33567c05fc865e26f971e954 diff --combined Documentation/glossary-content.txt index e225974253,c408d72582..cafc284359 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@@ -329,7 -329,7 +329,7 @@@ short form, the leading colon `:` is fo signature" letters (which optionally is terminated by another colon `:`), and the remainder is the pattern to match against the path. The "magic signature" consists of ASCII symbols that are neither -alphanumeric, glob, regex special charaters nor colon. +alphanumeric, glob, regex special characters nor colon. The optional colon that terminates the "magic signature" can be omitted if the pattern begins with a character that does not belong to "magic signature" symbol set and is not a colon. @@@ -411,28 -411,6 +411,28 @@@ exclude; core Git. Porcelains expose more of a <> interface than the <>. +[[def_per_worktree_ref]]per-worktree ref:: + Refs that are per-<>, rather than + global. This is presently only <> and any refs + that start with `refs/bisect/`, but might later include other + unusual refs. + +[[def_pseudoref]]pseudoref:: + Pseudorefs are a class of files under `$GIT_DIR` which behave + like refs for the purposes of rev-parse, but which are treated + specially by git. Pseudorefs both have names that are all-caps, + and always start with a line consisting of a + <> followed by whitespace. So, HEAD is not a + pseudoref, because it is sometimes a symbolic ref. They might + optionally contain some additional data. `MERGE_HEAD` and + `CHERRY_PICK_HEAD` are examples. Unlike + <>, these files cannot + be symbolic refs, and never have reflogs. They also cannot be + updated through the normal ref update machinery. Instead, + they are updated by directly writing to the files. However, + they can be read as if they were refs, so `git rev-parse + MERGE_HEAD` will work. + [[def_pull]]pull:: Pulling a <> means to <> it and <> it. See also linkgit:git-pull[1]. @@@ -491,11 -469,6 +491,11 @@@ The most notable example is `HEAD` <> to describe the mapping between remote <> and local ref. +[[def_remote]]remote repository:: + A <> which is used to track the same + project but resides somewhere else. To communicate with remotes, + see <> or <>. + [[def_remote_tracking_branch]]remote-tracking branch:: A <> that is used to follow changes from another <>. It typically looks like @@@ -531,6 -504,11 +531,11 @@@ "Secure Hash Algorithm 1"; a cryptographic hash function. In the context of Git used as a synonym for <>. + [[def_shallow_clone]]shallow clone:: + Mostly a synonym to <> + but the phrase makes it more explicit that it was created by + running `git clone --depth=...` command. + [[def_shallow_repository]]shallow repository:: A shallow <> has an incomplete history some of whose <> have <> cauterized away (in other @@@ -542,17 -520,6 +547,17 @@@ is created by giving the `--depth` option to linkgit:git-clone[1], and its history can be later deepened with linkgit:git-fetch[1]. +[[def_submodule]]submodule:: + A <> that holds the history of a + separate project inside another repository (the latter of + which is called <>). + +[[def_superproject]]superproject:: + A <> that references repositories + of other projects in its working tree as <>. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + [[def_symref]]symref:: Symbolic reference: instead of containing the <> id itself, it is of the format 'ref: refs/some/thing' and when diff --combined Documentation/user-manual.txt index 1c790ac74a,2a7d804aa1..ec6bacfcdf --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@@ -1200,7 -1200,7 +1200,7 @@@ for other users who clone your reposito If you wish the exclude patterns to affect only certain repositories (instead of every repository for a given project), you may instead put them in a file in your repository named `.git/info/exclude`, or in any -file specified by the `core.excludesfile` configuration variable. +file specified by the `core.excludesFile` configuration variable. Some Git commands can also take exclude patterns directly on the command line. See linkgit:gitignore[5] for the details. @@@ -1431,11 -1431,11 +1431,11 @@@ differently. Normally, a merge result parents, one pointing at each of the two lines of development that were merged. -However, if the current branch is a descendant of the other--so every -commit present in the one is already contained in the other--then Git -just performs a "fast-forward"; the head of the current branch is moved -forward to point at the head of the merged-in branch, without any new -commits being created. +However, if the current branch is an ancestor of the other--so every commit +present in the current branch is already contained in the other branch--then Git +just performs a "fast-forward"; the head of the current branch is moved forward +to point at the head of the merged-in branch, without any new commits being +created. [[fixing-mistakes]] Fixing mistakes @@@ -1491,7 -1491,7 +1491,7 @@@ resolving a merge>> [[fixing-a-mistake-by-rewriting-history]] Fixing a mistake by rewriting history -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just @@@ -2125,8 -2125,37 +2125,37 @@@ Allowing web browsing of a repositor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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/INSTALL in the Git source tree for instructions on setting it up. + project's revisions, file contents and logs without having to install + Git. Features like RSS/Atom feeds and blame/annotation details may + optionally be enabled. + + The linkgit:git-instaweb[1] command provides a simple way to start + browsing the repository using gitweb. The default server when using + instaweb is lighttpd. + + See the file gitweb/INSTALL in the Git source tree and + linkgit:gitweb[1] for instructions on details setting up a permament + installation with a CGI or Perl capable server. + + [[how-to-get-a-git-repository-with-minimal-history]] + How to get a Git repository with minimal history + ------------------------------------------------ + + A <>, with its truncated + history, is useful when one is interested only in recent history + of a project and getting full history from the upstream is + expensive. + + A <> is created by specifying + the linkgit:git-clone[1] `--depth` switch. The depth can later be + changed with the linkgit:git-fetch[1] `--depth` switch, or full + history restored with `--unshallow`. + + Merging inside a <> will work as long + as a merge base is in the recent history. + Otherwise, it will be like merging unrelated histories and may + have to result in huge conflicts. This limitation may make such + a repository unsuitable to be used in merge based workflows. [[sharing-development-examples]] Examples @@@ -3424,7 -3453,7 +3453,7 @@@ just missing one particular blob versio [[the-index]] The index ------------ +--------- The index is a binary file (generally kept in `.git/index`) containing a sorted list of path names, each with permissions and the SHA-1 of a blob @@@ -4230,9 -4259,9 +4259,9 @@@ Most of what `git rev-list` did is cont controls how and what revisions are walked, and more. The original job of `git rev-parse` is now taken by the function -`setup_revisions()`, which parses the revisions and the common command line +`setup_revisions()`, which parses the revisions and the common command-line options for the revision walker. This information is stored in the struct -`rev_info` for later consumption. You can do your own command line option +`rev_info` for later consumption. You can do your own command-line option parsing after calling `setup_revisions()`. After that, you have to call `prepare_revision_walk()` for initialization, and then you can get the commits one by one with the function `get_revision()`. @@@ -4636,23 -4665,15 +4665,15 @@@ Scan email archives for other stuff lef Scan man pages to see if any assume more background than this manual provides. - Simplify beginning by suggesting disconnected head instead of - temporary branch creation? - Add more good examples. Entire sections of just cookbook examples might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section? Include cross-references to the glossary, where appropriate. - Document shallow clones? See draft 1.5.0 release notes for some - documentation. - 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. Alternates, clone -reference, etc.