NAME
----
-gitcli - Git command line interface and conventions
+gitcli - Git command-line interface and conventions
SYNOPSIS
--------
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
+ 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.
see `hello.c` in your working tree with the former, but with the latter
you will.
+ * Just as the filesystem '.' (period) refers to the current directory,
+ using a '.' as a repository name in Git (a dot-repository) is a relative
+ path and means your current repository.
+
Here are the rules regarding the "flags" that you should follow when you are
scripting Git:
- * it's preferred to use the non dashed form of Git commands, which means that
+ * 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
+ * when a command-line option takes an argument, use the 'stuck' 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.
+ written in the 'stuck' 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.
- * many commands allow a long option "--option" to be abbreviated
+ * 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
+ 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",
+ new option whose name shares the same prefix, e.g. `--optimize`,
to make a short prefix that used to be unique no longer unique.
Magic Options
~~~~~~~~~~~~~
Commands which have the enhanced option parser activated all understand a
-couple of magic command line options:
+couple of magic command-line options:
-h::
gives a pretty printed usage of the command.
+
---------------------------------------------
$ git describe -h
-usage: git describe [options] <committish>*
+usage: git describe [options] <commit-ish>*
or: git describe [options] --dirty
--contains find the tag that comes after the commit
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.
+e.g. `git commit --amenity` option.
Separating argument from the option
----------------------------
However, this is *NOT* allowed for switches with an optional value, where the
-'sticked' form must be used:
+'stuck' form must be used:
----------------------------
$ git describe --abbrev HEAD # correct
$ git describe --abbrev=10 HEAD # correct