From 2a8f6dc6412a0d8c340c73f42533e1d1c5a98118 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 9 Jul 2007 08:48:38 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.3-rc0-81-g1ed84 --- config.txt | 5 ++++- git-checkout.html | 7 +++--- git-checkout.txt | 5 +++-- git-config.html | 7 ++++-- gitattributes.html | 50 ++++++++++++++++++++++++++++++++++++----- gitattributes.txt | 55 ++++++++++++++++++++++++++++++++++++++++++---- tutorial.html | 4 ++-- tutorial.txt | 2 +- user-manual.html | 21 +++++++++++------- user-manual.txt | 27 ++++++++++++++++++----- 10 files changed, 150 insertions(+), 33 deletions(-) diff --git a/config.txt b/config.txt index 4b67f0adf..aeece848a 100644 --- a/config.txt +++ b/config.txt @@ -309,7 +309,10 @@ branch.autosetupmerge:: so that gitlink:git-pull[1] will appropriately merge from that remote branch. Note that even if this option is not set, this behavior can be chosen per-branch using the `--track` - and `--no-track` options. This option defaults to false. + and `--no-track` options. This option can have values + 'false' (never touch the configuration), 'all' (do this + for all branches), or 'true' (do this only when + branching from a remote tracking branch), and defaults to 'true'. branch..remote:: When in branch , it tells `git fetch` which remote to fetch. diff --git a/git-checkout.html b/git-checkout.html index 43989db03..ac5f81603 100644 --- a/git-checkout.html +++ b/git-checkout.html @@ -334,8 +334,9 @@ working tree.

set up configuration so that git-pull will automatically retrieve data from the remote branch. Set the branch.autosetupmerge configuration variable to true if you - want git-checkout and git-branch to always behave as if - --track were given. + want git-checkout and git-branch to behave as if + --track were given when you branch from a remote + tracking branch.

@@ -538,7 +539,7 @@ $ git add frotz diff --git a/git-checkout.txt b/git-checkout.txt index 818b720b9..82929523c 100644 --- a/git-checkout.txt +++ b/git-checkout.txt @@ -52,8 +52,9 @@ OPTIONS set up configuration so that git-pull will automatically retrieve data from the remote branch. Set the branch.autosetupmerge configuration variable to true if you - want git-checkout and git-branch to always behave as if - '--track' were given. + want git-checkout and git-branch to behave as if + '--track' were given when you branch from a remote + tracking branch. --no-track:: When -b is given and a branch is created off a remote branch, diff --git a/git-config.html b/git-config.html index 5e46547f9..8dbcb06f7 100644 --- a/git-config.html +++ b/git-config.html @@ -1060,7 +1060,10 @@ branch.autosetupmerge so that git-pull(1) will appropriately merge from that remote branch. Note that even if this option is not set, this behavior can be chosen per-branch using the --track - and --no-track options. This option defaults to false. + and --no-track options. This option can have values + false (never touch the configuration), all (do this + for all branches), or true (do this only when + branching from a remote tracking branch), and defaults to true.

@@ -1839,7 +1842,7 @@ transfer.unpackLimit diff --git a/gitattributes.html b/gitattributes.html index 59e39e78d..e8b3b5b83 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -347,8 +347,8 @@ the name of the attribute prefixed with an exclamation point !.

EFFECTS

Certain operations by git can be influenced by assigning -particular attributes to a path. Currently, three operations -are attributes-aware.

+particular attributes to a path. Currently, the following +operations are attributes-aware.

Checking-out and checking-in

These attributes affect how the contents stored in the repository are copied to the working tree files when commands @@ -454,7 +454,9 @@ and applicable).

with crlf, and then ident and fed to filter.

Generating diff text

The attribute diff affects if git diff generates textual -patch for the path or just says Binary files differ.

+patch for the path or just says Binary files differ. It also +can affect what line is shown on the hunk header @@ -k,l +n,m @@ +line.

Set @@ -494,7 +496,8 @@ String Diff is shown using the specified custom diff driver. The driver program is given its input using the same calling convention as used for GIT_EXTERNAL_DIFF - program. + program. This name is also used for custom hunk header + selection.

@@ -514,6 +517,43 @@ attribute set to jcdiff, it calls the command you specified with the above configuration, i.e. j-c-diff, with 7 parameters, just like GIT_EXTERNAL_DIFF program is called. See git(7) for details.

+

Defining a custom hunk-header

+

Each group of changes (called "hunk") in the textual diff output +is prefixed with a line of the form:

+
+
+
@@ -k,l +n,m @@ TEXT
+
+

The text is called hunk header, and by default a line that +begins with an alphabet, an underscore or a dollar sign is used, +which matches what GNU diff -p output uses. This default +selection however is not suited for some contents, and you can +use customized pattern to make a selection.

+

First in .gitattributes, you would assign the diff attribute +for paths.

+
+
+
*.tex   diff=tex
+
+

Then, you would define "diff.tex.funcname" configuration to +specify a regular expression that matches a line that you would +want to appear as the hunk header, like this:

+
+
+
[diff "tex"]
+        funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$"
+
+

Note. A single level of backslashes are eaten by the +configuration file parser, so you would need to double the +backslashes; the pattern above picks a line that begins with a +backslash, and zero or more occurences of sub followed by +section followed by open brace, to the end of line.

+

There are a few built-in patterns to make this easier, and tex +is one of them, so you do not have to write the above in your +configuration file (you still need to enable this with the +attribute mechanism, via .gitattributes). Another built-in +pattern is defined for java that defines a pattern suitable +for program text in Java language.

Performing a three-way merge

The attribute merge affects how three versions of a file is merged when a file-level merge is necessary during git merge, @@ -658,7 +698,7 @@ frotz unspecified

diff --git a/gitattributes.txt b/gitattributes.txt index d3ac9c718..810df0721 100644 --- a/gitattributes.txt +++ b/gitattributes.txt @@ -72,8 +72,8 @@ EFFECTS ------- Certain operations by git can be influenced by assigning -particular attributes to a path. Currently, three operations -are attributes-aware. +particular attributes to a path. Currently, the following +operations are attributes-aware. Checking-out and checking-in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,7 +199,9 @@ Generating diff text ~~~~~~~~~~~~~~~~~~~~ The attribute `diff` affects if `git diff` generates textual -patch for the path or just says `Binary files differ`. +patch for the path or just says `Binary files differ`. It also +can affect what line is shown on the hunk header `@@ -k,l +n,m @@` +line. Set:: @@ -224,7 +226,8 @@ String:: Diff is shown using the specified custom diff driver. The driver program is given its input using the same calling convention as used for GIT_EXTERNAL_DIFF - program. + program. This name is also used for custom hunk header + selection. Defining a custom diff driver @@ -249,6 +252,50 @@ parameters, just like `GIT_EXTERNAL_DIFF` program is called. See gitlink:git[7] for details. +Defining a custom hunk-header +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each group of changes (called "hunk") in the textual diff output +is prefixed with a line of the form: + + @@ -k,l +n,m @@ TEXT + +The text is called 'hunk header', and by default a line that +begins with an alphabet, an underscore or a dollar sign is used, +which matches what GNU `diff -p` output uses. This default +selection however is not suited for some contents, and you can +use customized pattern to make a selection. + +First in .gitattributes, you would assign the `diff` attribute +for paths. + +------------------------ +*.tex diff=tex +------------------------ + +Then, you would define "diff.tex.funcname" configuration to +specify a regular expression that matches a line that you would +want to appear as the hunk header, like this: + +------------------------ +[diff "tex"] + funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" +------------------------ + +Note. A single level of backslashes are eaten by the +configuration file parser, so you would need to double the +backslashes; the pattern above picks a line that begins with a +backslash, and zero or more occurences of `sub` followed by +`section` followed by open brace, to the end of line. + +There are a few built-in patterns to make this easier, and `tex` +is one of them, so you do not have to write the above in your +configuration file (you still need to enable this with the +attribute mechanism, via `.gitattributes`). Another built-in +pattern is defined for `java` that defines a pattern suitable +for program text in Java language. + + Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/tutorial.html b/tutorial.html index 4528590f9..95bed9f50 100644 --- a/tutorial.html +++ b/tutorial.html @@ -520,7 +520,7 @@ it easier:

$ git remote add bob /home/bob/myrepo
-

With this, you can perform the first operation alone using the +

With this, Alice can perform the first operation alone using the "git fetch" command without merging them with her own branch, using:

@@ -786,7 +786,7 @@ digressions that may be interesting at this point are:

diff --git a/tutorial.txt b/tutorial.txt index 53403c6db..bd9fbee99 100644 --- a/tutorial.txt +++ b/tutorial.txt @@ -304,7 +304,7 @@ it easier: $ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, you can perform the first operation alone using the +With this, Alice can perform the first operation alone using the "git fetch" command without merging them with her own branch, using: diff --git a/user-manual.html b/user-manual.html index 0e605b607..08c857f71 100644 --- a/user-manual.html +++ b/user-manual.html @@ -372,7 +372,7 @@ but not from these other heads:

$ commits reachable from some head but not from any tag in the repository:

$ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )

(See git-rev-parse(1) for explanations of commit-selecting syntax such as —not.)

Creating a changelog and tarball for a software release

The git-archive(1) command can create a tar or zip archive from any version of a project; for example:

$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz

will use HEAD to produce a tar archive in which each filename is -preceded by "prefix/".

If you're releasing a new version of a software project, you may want +preceded by "project/".

If you're releasing a new version of a software project, you may want to simultaneously make a changelog to include in the release announcement.

Linus Torvalds, for example, makes new kernel releases by tagging them, then running:

$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7

where release-script is a shell script that looks like:

#!/bin/sh
@@ -630,9 +630,9 @@ dangling dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
...

Dangling objects are not a problem. At worst they may take up a little -extra disk space. They can sometimes provide a last-resort method of -recovery lost work—see the section called “Dangling objects” for details. However, if -you want, you may remove them with git-prune(1) or the —prune +extra disk space. They can sometimes provide a last-resort method for +recovering lost work—see the section called “Dangling objects” for details. However, if +you wish, you can remove them with git-prune(1) or the —prune option to git-gc(1):

$ git gc --prune

This may be time-consuming. Unlike most other git operations (including git-gc when run without any options), it is not safe to prune while other git operations are in progress in the same repository.

Recovering lost changes

Reflogs

Say you modify a branch with git-reset(1) —hard, and then @@ -713,9 +713,10 @@ that project to pull the changes from your repository using git-pull[1]. In the section "Getting updates with git pull" we described this as a way to get updates from the "main" repository, but it works just as well in the other direction.

If you and the maintainer both have accounts on the same machine, then you can just pull changes from each other's repositories directly; -commands that accepts repository URLs as arguments will also accept a +commands that accept repository URLs as arguments will also accept a local directory name:

$ git clone /path/to/repository
-$ git pull /path/to/other/repository

However, the more common way to do this is to maintain a separate public +$ git pull /path/to/other/repository

or an ssh url:

$ git clone ssh://yourhost/~you/repository

For projects with few developers, or for synchronizing a few private +repositories, this may be all you need.

However, the more common way to do this is to maintain a separate public repository (usually on a different host) for others to pull changes from. This is usually more convenient, and allows you to cleanly separate private work in progress from publicly visible work.

You will continue to do your day-to-day work in your personal @@ -731,7 +732,7 @@ your personal repo ------------------> your public repo | | | | | they push V -their public repo <------------------- their repo

Setting up a public repository

Assume your personal repository is in the directory ~/proj. We +their public repo <------------------- their repo

We explain how to do this in the following sections.

Setting up a public repository

Assume your personal repository is in the directory ~/proj. We first create a new clone of the repository and tell git-daemon that it is meant to be public:

$ git clone --bare ~/proj proj.git
$ touch proj.git/git-daemon-export-ok

The resulting directory proj.git contains a "bare" git repository—it is @@ -769,7 +770,11 @@ branch named "master", run

$ a fast forward. Normally this is a sign of something wrong. However, if you are sure you know what you're doing, you may force git-push to perform the update anyway by -proceeding the branch name by a plus sign:

$ git push ssh://yourserver.com/~you/proj.git +master

As with git-fetch, you may also set up configuration options to +proceeding the branch name by a plus sign:

$ git push ssh://yourserver.com/~you/proj.git +master

Note that the target of a "push" is normally a +bare repository. You can also push to a +repository that has a checked-out working tree, but the working tree +will not be updated by the push. This may lead to unexpected results if +the branch you push to is the currently checked-out branch!

As with git-fetch, you may also set up configuration options to save typing; so, for example, after

$ cat >>.git/config <<EOF
[remote "public-repo"]
        url = ssh://yourserver.com/~you/proj.git
diff --git a/user-manual.txt b/user-manual.txt index c23077c72..14825c641 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -890,7 +890,7 @@ $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz ------------------------------------------------- will use HEAD to produce a tar archive in which each filename is -preceded by "prefix/". +preceded by "project/". If you're releasing a new version of a software project, you may want to simultaneously make a changelog to include in the release @@ -1528,9 +1528,9 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ------------------------------------------------- Dangling objects are not a problem. At worst they may take up a little -extra disk space. They can sometimes provide a last-resort method of -recovery lost work--see <> for details. However, if -you want, you may remove them with gitlink:git-prune[1] or the --prune +extra disk space. They can sometimes provide a last-resort method for +recovering lost work--see <> for details. However, if +you wish, you can remove them with gitlink:git-prune[1] or the --prune option to gitlink:git-gc[1]: ------------------------------------------------- @@ -1772,7 +1772,7 @@ repository, but it works just as well in the other direction. If you and the maintainer both have accounts on the same machine, then you can just pull changes from each other's repositories directly; -commands that accepts repository URLs as arguments will also accept a +commands that accept repository URLs as arguments will also accept a local directory name: ------------------------------------------------- @@ -1780,6 +1780,15 @@ $ git clone /path/to/repository $ git pull /path/to/other/repository ------------------------------------------------- +or an ssh url: + +------------------------------------------------- +$ git clone ssh://yourhost/~you/repository +------------------------------------------------- + +For projects with few developers, or for synchronizing a few private +repositories, this may be all you need. + However, the more common way to do this is to maintain a separate public repository (usually on a different host) for others to pull changes from. This is usually more convenient, and allows you to cleanly @@ -1802,6 +1811,8 @@ like this: | they push V their public repo <------------------- their repo +We explain how to do this in the following sections. + [[setting-up-a-public-repository]] Setting up a public repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1913,6 +1924,12 @@ proceeding the branch name by a plus sign: $ git push ssh://yourserver.com/~you/proj.git +master ------------------------------------------------- +Note that the target of a "push" is normally a +<> repository. You can also push to a +repository that has a checked-out working tree, but the working tree +will not be updated by the push. This may lead to unexpected results if +the branch you push to is the currently checked-out branch! + As with git-fetch, you may also set up configuration options to save typing; so, for example, after -- 2.26.2