diff options
Diffstat (limited to 'Documentation/gitcli.txt')
| -rw-r--r-- | Documentation/gitcli.txt | 51 |
1 files changed, 43 insertions, 8 deletions
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index f734f97b8e..3bc1500eda 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -25,22 +25,39 @@ arguments. Here are the rules: are paths. * When an argument can be misunderstood as either a revision or a path, - they can be disambiguated by placing `\--` between them. - E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work + they can be disambiguated by placing `--` between them. + E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index and what I have in the work tree for that file". not "show difference between the HEAD commit and the work tree as a whole". You can say - `git diff HEAD \--` to ask for the latter. + `git diff HEAD --` to ask for the latter. - * Without disambiguating `\--`, git makes a reasonable guess, but errors + * Without disambiguating `--`, git makes a reasonable guess, but errors out and asking you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, `git diff HEAD` is ambiguous, and - you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to + you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. - ++ When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing -disambiguating `\--` at appropriate places. +disambiguating `--` at appropriate places. + + * Many commands allow wildcards in paths, but you need to protect + them from getting globbed by the shell. These two mean different + things: ++ +-------------------------------- +$ git checkout -- *.c +$ git checkout -- \*.c +-------------------------------- ++ +The former lets your shell expand the fileglob, and you are asking +the dot-C files in your working tree to be overwritten with the version +in the index. The latter passes the `*.c` to Git, and you are asking +the paths in the index that match the pattern to be checked out to your +working tree. After running `git add hello.c; rm hello.c`, you will _not_ +see `hello.c` in your working tree with the former, but with the latter +you will. Here are the rules regarding the "flags" that you should follow when you are scripting git: @@ -62,13 +79,21 @@ scripting git: `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. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- 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. +Here is a list of the facilities provided by this option parser. Magic Options @@ -112,6 +137,16 @@ options. This means that you can for example use `git rm -rf` or `git clean -fdx`. +Abbreviating long options +~~~~~~~~~~~~~~~~~~~~~~~~~ +Commands that support the enhanced option parser accepts unique +prefix of a long option as if it is fully spelled out, but use this +with a caution. For example, `git commit --amen` behaves as if you +typed `git commit --amend`, but that is true only until a later version +of Git introduces another option that shares the same prefix, +e.g `git commit --amenity" option. + + Separating argument from the option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can write the mandatory option parameter to an option as a separate |