NAME
----
-gitcli - git command line interface and conventions
+gitcli - Git command line interface and conventions
SYNOPSIS
--------
DESCRIPTION
-----------
-This manual describes the convention used throughout git CLI.
+This manual describes the convention used throughout Git CLI.
Many commands take revisions (most often "commits", but sometimes
"tree-ish", depending on the context and command) and paths as their
between the HEAD commit and the work tree as a whole". You can say
`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
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:
+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`
`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.
ENHANCED OPTION PARSER
----------------------
-From the git 1.5.4 series and further, many git commands (not all of them at the
+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 a list of the facilities provided by this option parser.
+
---------------------------------------------
$ 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
--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)
+ --all use any ref
+ --tags use any tag, even unannotated
+ --long always use long format
+ --abbrev[=<n>] use <n> digits to display SHA-1s
---------------------------------------------
--help-all::
- Some git commands take options that are only used for plumbing or that
+ 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.
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