From: Junio C Hamano Date: Sun, 23 Dec 2007 08:16:38 +0000 (+0000) Subject: Autogenerated HTML docs for v1.5.4-rc1-21-g0e545 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=f556fc2a7c28ca2b4097c2c8b0180de3b8ca7238;p=git.git Autogenerated HTML docs for v1.5.4-rc1-21-g0e545 --- diff --git a/git-check-attr.html b/git-check-attr.html index d93730dca..1a3c0331b 100644 --- a/git-check-attr.html +++ b/git-check-attr.html @@ -294,6 +294,10 @@ git-check-attr(1) Manual Page +

SEE ALSO

+
+

gitattributes(5).

+

Author

Written by Junio C Hamano <junkio@cox.net>

@@ -308,7 +312,7 @@ git-check-attr(1) Manual Page
diff --git a/git-check-attr.txt b/git-check-attr.txt index 856d2af2e..47cb1bdfa 100644 --- a/git-check-attr.txt +++ b/git-check-attr.txt @@ -23,6 +23,11 @@ OPTIONS be treated as an attribute. +SEE ALSO +-------- +gitlink:gitattributes[5]. + + Author ------ Written by Junio C Hamano diff --git a/git-ls-files.html b/git-ls-files.html index 4aeeb3810..9103ec33a 100644 --- a/git-ls-files.html +++ b/git-ls-files.html @@ -507,7 +507,8 @@ other

Similar to -t, but use lowercase letters for files - that are marked as always matching index. + that are marked as assume unchanged (see + git-update-index(1)).

@@ -625,7 +626,7 @@ pattern file appears in.

diff --git a/git-ls-files.txt b/git-ls-files.txt index 2ec0c0d27..d0c3aa21d 100644 --- a/git-ls-files.txt +++ b/git-ls-files.txt @@ -105,7 +105,8 @@ OPTIONS -v:: Similar to `-t`, but use lowercase letters for files - that are marked as 'always matching index'. + that are marked as 'assume unchanged' (see + gitlink:git-update-index[1]). --full-name:: When run from a subdirectory, the command usually diff --git a/git-merge.html b/git-merge.html index d075ef769..209d0b33d 100644 --- a/git-merge.html +++ b/git-merge.html @@ -632,7 +632,8 @@ Resolve the conflicts. git-diff would report only the

SEE ALSO

-

git-fmt-merge-msg(1), git-pull(1)

+

git-fmt-merge-msg(1), git-pull(1), +gitattributes(5)

Author

@@ -648,7 +649,7 @@ Resolve the conflicts. git-diff would report only the
diff --git a/git-merge.txt b/git-merge.txt index eabd7ef33..1521a9ee0 100644 --- a/git-merge.txt +++ b/git-merge.txt @@ -163,7 +163,8 @@ After seeing a conflict, you can do two things: SEE ALSO -------- -gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1] +gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1], +gitlink:gitattributes[5] Author diff --git a/gitattributes.html b/gitattributes.html index 488ddc3ba..b53e571a7 100644 --- a/gitattributes.html +++ b/gitattributes.html @@ -599,10 +599,51 @@ String

+

Built-in merge drivers

+

There are a few built-in low-level merge drivers defined that +can be asked for via the merge attribute.

+
+
+text +
+
+

+ Usual 3-way file level merge for text files. Conflicted + regions are marked with conflict markers <<<<<<<, + ======= and >>>>>>>. The version from your branch + appears before the ======= marker, and the version + from the merged branch appears after the ======= + marker. +

+
+
+binary +
+
+

+ Keep the version from your branch in the work tree, but + leave the path in the conflicted state for the user to + sort out. +

+
+
+union +
+
+

+ Run 3-way file level merge for text files, but take + lines from both versions, instead of leaving conflict + markers. This tends to leave the added lines in the + resulting file in random order and the user should + verify the result. Do not use this if you do not + understand the implications. +

+
+

Defining a custom merge driver

-

The definition of a merge driver is done in gitconfig not -gitattributes file, so strictly speaking this manual page is a -wrong place to talk about it. However…

+

The definition of a merge driver is done in the .git/config +file, not in the gitattributes file, so strictly speaking this +manual page is a wrong place to talk about it. However…

To define a custom merge driver filfre, add a section to your $GIT_DIR/config file (or $HOME/.gitconfig file) like this:

@@ -746,7 +787,7 @@ commit hash.

diff --git a/gitattributes.txt b/gitattributes.txt index 71c7ad76d..cc9c7c52c 100644 --- a/gitattributes.txt +++ b/gitattributes.txt @@ -322,12 +322,43 @@ String:: requested with "binary". +Built-in merge drivers +^^^^^^^^^^^^^^^^^^^^^^ + +There are a few built-in low-level merge drivers defined that +can be asked for via the `merge` attribute. + +text:: + + Usual 3-way file level merge for text files. Conflicted + regions are marked with conflict markers `<<<<<<<`, + `=======` and `>>>>>>>`. The version from your branch + appears before the `=======` marker, and the version + from the merged branch appears after the `=======` + marker. + +binary:: + + Keep the version from your branch in the work tree, but + leave the path in the conflicted state for the user to + sort out. + +union:: + + Run 3-way file level merge for text files, but take + lines from both versions, instead of leaving conflict + markers. This tends to leave the added lines in the + resulting file in random order and the user should + verify the result. Do not use this if you do not + understand the implications. + + Defining a custom merge driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The definition of a merge driver is done in `gitconfig` not -`gitattributes` file, so strictly speaking this manual page is a -wrong place to talk about it. However... +The definition of a merge driver is done in the `.git/config` +file, not in the `gitattributes` file, so strictly speaking this +manual page is a wrong place to talk about it. However... To define a custom merge driver `filfre`, add a section to your `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: diff --git a/gitcli.html b/gitcli.html new file mode 100644 index 000000000..0a6bad1c1 --- /dev/null +++ b/gitcli.html @@ -0,0 +1,395 @@ + + + + + + +gitcli(5) + + + +

SYNOPSIS

+
+

gitcli

+
+

DESCRIPTION

+
+

This manual describes best practice in how to use git CLI. Here are +the rules that you should follow when you are scripting git:

+
    +
  • +

    +it's preferred to use the non dashed form of git commands, which means that + you should prefer "git foo" to "git-foo". +

    +
    • +
  • +

    +splitting short options to separate words (prefer "git foo -a -b" + to "git foo -ab", the latter may not even work). +

    +
    • +
  • +

    +when a command line option takes an argument, use the sticked form. In + other words, write "git foo -oArg" instead of "git foo -o Arg" for short + options, and "git foo --long-opt=Arg" instead of "git foo --long-opt Arg" + for long options. An option that takes optional option-argument must be + written in the sticked form. +

    +
    • +
  • +

    +when you give a revision parameter to a command, make sure the parameter is + not ambiguous with a name of a file in the work tree. E.g. do not write + "git log -1 HEAD" but write "git log -1 HEAD --"; the former will not work + if you happen to have a file called HEAD in the work tree. +

    +
    • +
+
+

ENHANCED CLI

+
+

From the git 1.5.4 series and further, many git commands (not all of them at the +time of the writing though) come with an enhanced option parser.

+

Here is an exhaustive list of the facilities provided by this option parser.

+

Magic Options

+

Commands which have the enhanced option parser activated all understand a +couple of magic command line options:

+
+
+-h +
+
+

+ gives a pretty printed usage of the command. +

+
+
+
$ git describe -h
+usage: git-describe [options] <committish>*
+
+    --contains            find the tag that comes after the commit
+    --debug               debug search strategy on stderr
+    --all                 use any ref in .git/refs
+    --tags                use any tag in .git/refs/tags
+    --abbrev [<n>]        use <n> digits to display SHA-1s
+    --candidates <n>      consider <n> most recent tags (default: 10)
+
+
+
+--help-all +
+
+

+ Some git commands take options that are only used for plumbing or that + are deprecated, and such options are hidden from the default usage. This + option gives the full list of options. +

+
+
+

Negating options

+

Options with long option names can be negated by prefixing "--no-". For +example, "git branch" has the option "--track" which is on by default. You +can use "--no-track" to override that behaviour. The same goes for "--color" +and "--no-color".

+

Aggregating short options

+

Commands that support the enhanced option parser allow you to aggregate short +options. This means that you can for example use "git rm -rf" or +"git clean -fdx".

+

Separating argument from the option

+

You can write the mandatory option parameter to an option as a separate +word on the command line. That means that all the following uses work:

+
+
+
$ git foo --long-opt=Arg
+$ git foo --long-opt Arg
+$ git foo -oArg
+$ git foo -o Arg
+
+

However, this is NOT allowed for switches with an optionnal value, where the +sticked form must be used:

+
+
+
$ git describe --abbrev HEAD     # correct
+$ git describe --abbrev=10 HEAD  # correct
+$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT
+
+
+

Documentation

+
+

Documentation by Pierre Habouzit.

+
+

GIT

+
+

Part of the git(7) suite

+
+ + + diff --git a/gitcli.txt b/gitcli.txt new file mode 100644 index 000000000..b7dcf9ca1 --- /dev/null +++ b/gitcli.txt @@ -0,0 +1,113 @@ +gitcli(5) +========= + +NAME +---- +gitcli - git command line interface and conventions + +SYNOPSIS +-------- +gitcli + + +DESCRIPTION +----------- + +This manual describes best practice in how to use git CLI. Here are +the rules that you should follow when you are scripting git: + + * it's preferred to use the non dashed form of git commands, which means that + you should prefer `"git foo"` to `"git-foo"`. + + * splitting short options to separate words (prefer `"git foo -a -b"` + to `"git foo -ab"`, the latter may not even work). + + * when a command line option takes an argument, use the 'sticked' form. In + other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short + options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"` + for long options. An option that takes optional option-argument must be + written in the 'sticked' form. + + * when you give a revision parameter to a command, make sure the parameter is + not ambiguous with a name of a file in the work tree. E.g. do not write + `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work + if you happen to have a file called `HEAD` in the work tree. + + +ENHANCED CLI +------------ +From the git 1.5.4 series and further, many git commands (not all of them at the +time of the writing though) come with an enhanced option parser. + +Here is an exhaustive list of the facilities provided by this option parser. + + +Magic Options +~~~~~~~~~~~~~ +Commands which have the enhanced option parser activated all understand a +couple of magic command line options: + +-h:: + gives a pretty printed usage of the command. ++ +--------------------------------------------- +$ git describe -h +usage: git-describe [options] * + + --contains find the tag that comes after the commit + --debug debug search strategy on stderr + --all use any ref in .git/refs + --tags use any tag in .git/refs/tags + --abbrev [] use digits to display SHA-1s + --candidates consider most recent tags (default: 10) +--------------------------------------------- + +--help-all:: + Some git commands take options that are only used for plumbing or that + are deprecated, and such options are hidden from the default usage. This + option gives the full list of options. + + +Negating options +~~~~~~~~~~~~~~~~ +Options with long option names can be negated by prefixing `"--no-"`. For +example, `"git branch"` has the option `"--track"` which is 'on' by default. You +can use `"--no-track"` to override that behaviour. The same goes for `"--color"` +and `"--no-color"`. + + +Aggregating short options +~~~~~~~~~~~~~~~~~~~~~~~~~ +Commands that support the enhanced option parser allow you to aggregate short +options. This means that you can for example use `"git rm -rf"` or +`"git clean -fdx"`. + + +Separating argument from the option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can write the mandatory option parameter to an option as a separate +word on the command line. That means that all the following uses work: + +---------------------------- +$ git foo --long-opt=Arg +$ git foo --long-opt Arg +$ git foo -oArg +$ git foo -o Arg +---------------------------- + +However, this is *NOT* allowed for switches with an optionnal value, where the +'sticked' form must be used: +---------------------------- +$ git describe --abbrev HEAD # correct +$ git describe --abbrev=10 HEAD # correct +$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT +---------------------------- + + +Documentation +------------- +Documentation by Pierre Habouzit. + +GIT +--- +Part of the gitlink:git[7] suite