- We do not use Process Substitution <(list) or >(list).
+ - Do not write control structures on a single line with semicolon.
+ "then" should be on the next line for if statements, and "do"
+ should be on the next line for "while" and "for".
+
- We prefer "test" over "[ ... ]".
- We do not write the noiseword "function" in front of shell
functions.
+ - We prefer a space between the function name and the parentheses. The
+ opening "{" should also be on the same line.
+ E.g.: my_function () {
+
- As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
[::], [==], nor [..]) for portability.
--- /dev/null
+Git v1.7.11.6 Release Notes
+===========================
+
+Fixes since v1.7.11.5
+---------------------
+
+This is primarily documentation and low-impact code clarification.
+
+ - "ciabot" script (in contrib/) has been updated with extensive
+ documentation.
+
+ - The "--rebase" option to "git pull" can be abbreviated to "-r",
+ but we didn't document it.
+
+ - It was generally understood that "--long-option"s to many of our
+ subcommands can be abbreviated to the unique prefix, but it was not
+ easy to find it described for new readers of the documentation set.
+
+ - The "--topo-order", "--date-order" (and the lack of either means
+ the default order) options to "rev-list" and "log" family of
+ commands were poorly described in the documentation.
+
+ - Older parts of the documentation described as if having a regular
+ file in .git/refs/ hierarchy were the only way to have branches and
+ tags, which is not true for quite some time.
+
+ - A utility shell function test_seq has been added as a replacement
+ for the 'seq' utility found on some platforms.
+
+ - Fallback 'getpass' implementation made unportable use of stdio API.
+
+ - "git commit --amend" let the user edit the log message and then
+ died when the human-readable committer name was given
+ insufficiently by getpwent(3).
--all::
Instead of using only the annotated tags, use any ref
- found in `.git/refs/`. This option enables matching
+ found in `refs/` namespace. This option enables matching
any known branch, remote-tracking branch, or lightweight tag.
--tags::
Instead of using only the annotated tags, use any tag
- found in `.git/refs/tags`. This option enables matching
+ found in `refs/tags` namespace. This option enables matching
a lightweight (non-annotated) tag.
--contains::
useful in the future for compensating for some git bugs or such,
therefore such a usage is permitted.
-*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`.
+*NOTE*: This command honors `.git/info/grafts` file and refs in
+the `refs/replace/` namespace.
If you have any grafts or replacement refs defined, running this command
will make them permanent.
An object to treat as the head of an unreachability trace.
+
If no objects are given, 'git fsck' defaults to using the
-index file, all SHA1 references in .git/refs/*, and all reflogs (unless
---no-reflogs is given) as heads.
+index file, all SHA1 references in `refs` namespace, and all reflogs
+(unless --no-reflogs is given) as heads.
--unreachable::
Print out objects that exist but that aren't reachable from any
------------
After making sure you know which the object is the tag you are looking
-for, you can reconnect it to your regular .git/refs hierarchy.
+for, you can reconnect it to your regular `refs` hierarchy by using
+the `update-ref` command.
------------
$ git cat-file -t 1ef2b196
-----------
Traditionally, tips of branches and tags (collectively known as
-'refs') were stored one file per ref under `$GIT_DIR/refs`
+'refs') were stored one file per ref in a (sub)directory
+under `$GIT_DIR/refs`
directory. While many branch tips tend to be updated often,
most tags and some branch tips are never updated. When a
repository has hundreds or thousands of tags, this
performance.
This command is used to solve the storage and performance
-problem by stashing the refs in a single file,
+problem by storing the refs in a single file,
`$GIT_DIR/packed-refs`. When a ref is missing from the
-traditional `$GIT_DIR/refs` hierarchy, it is looked up in this
+traditional `$GIT_DIR/refs` directory hierarchy, it is looked
+up in this
file and used if found.
Subsequent updates to branches always create new files under
-`$GIT_DIR/refs` hierarchy.
+`$GIT_DIR/refs` directory hierarchy.
A recommended practice to deal with a repository with too many
refs is to pack its refs with `--all --prune` once, and
The command usually removes loose refs under `$GIT_DIR/refs`
hierarchy after packing them. This option tells it not to.
+
+BUGS
+----
+
+Older documentation written before the packed-refs mechanism was
+introduced may still say things like ".git/refs/heads/<branch> file
+exists" when it means "branch <branch> exists".
+
+
GIT
---
Part of the linkgit:git[1] suite
:git-pull: 1
+-r::
--rebase::
Rebase the current branch on top of the upstream branch after
fetching. If there is a remote-tracking branch corresponding to
DESCRIPTION
-----------
-Adds a 'replace' reference in `.git/refs/replace/`
+Adds a 'replace' reference in `refs/replace/` namespace.
The name of the 'replace' reference is the SHA1 of the object that is
replaced. The content of the 'replace' reference is the SHA1 of the
replacement object.
-Unless `-f` is given, the 'replace' reference must not yet exist in
-`.git/refs/replace/` directory.
+Unless `-f` is given, the 'replace' reference must not yet exist.
Replacement references will be used by default by all git commands
except those doing reachability traversal (prune, pack transfer and
DESCRIPTION
-----------
-Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
+Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
to delete, list or verify tags.
-Unless `-f` is given, the tag to be created must not yet exist in the
-`.git/refs/tags/` directory.
+Unless `-f` is given, the named tag must not yet exist.
If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
creates a 'tag' object, and requires a tag message. Unless
`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
----------------------
By default, the commits are shown in reverse chronological order.
---topo-order::
+--date-order::
+ Show no parents before all of its children are shown, but
+ otherwise show commits in the commit timestamp order.
- This option makes them appear in topological order (i.e.
- descendant commits are shown before their parents).
+--topo-order::
+ Show no parents before all of its children are shown, and
+ avoid showing commits on multiple lines of history
+ intermixed.
++
+For example, in a commit history like this:
++
+----------------------------------------------------------------
---date-order::
+ ---1----2----4----7
+ \ \
+ 3----5----6----8---
- This option is similar to '--topo-order' in the sense that no
- parent comes before all of its children, but otherwise things
- are still ordered in the commit timestamp order.
+----------------------------------------------------------------
++
+where the numbers denote the order of commit timestamps, `git
+rev-list` and friends with `--date-order` show the commits in the
+timestamp order: 8 7 6 5 4 3 2 1.
++
+With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
+3 1); some older commits are shown before newer ones in order to
+avoid showing the commits from two parallel development track mixed
+together.
--reverse::
--- /dev/null
+= Installation instructions =
+
+Two scripts are included. The Python one (ciabot.py) is faster and
+more capable; the shell one (ciabot.sh) is a fallback in case Python
+gives your git hosting site indigestion. (I know of no such sites.)
+
+It is no longer necessary to modify the script in order to put it
+in place; in fact, this is now discouraged. It is entirely
+configurable with the following git config variables:
+
+ciabot.project = name of the project
+ciabot.repo = name of the project repo for gitweb/cgit purposes
+ciabot.xmlrpc = if true, ship notifications via XML-RPC
+ciabot.revformat = format in which the revision is shown
+
+The revformat variable may have the following values
+raw -> full hex ID of commit
+short -> first 12 chars of hex ID
+describe -> describe relative to last tag, falling back to short
+
+ciabot.project defaults to the directory name of the repository toplevel.
+ciabot.repo defaults to ciabot.project lowercased.
+ciabot.xmlrpc defaults to True
+ciabot.revformat defaults to 'describe'.
+
+This means that in the normal case you need not do any configuration at all,
+however setting ciabot.project will allow the hook to run slightly faster.
+
+Once you've set these variables, try your script with -n to see the
+notification message dumped to stdout and verify that it looks sane.
+
+To live-test these scripts, your project needs to have been registered with
+the CIA site. Here are the steps:
+
+1. Open an IRC window on irc://freenode/commits or your registered
+ project IRC channel.
+
+2. Run ciabot.py and/or ciabot.sh from any directory under git
+ control.
+
+You should see a notification on the channel for your most recent commit.
+
+After verifying correct function, install one of these scripts either
+in a post-commit hook or in an update hook.
+
+In post-commit, run it without arguments. It will query for
+current HEAD and the latest commit ID to get the information it
+needs.
+
+In update, call it with a refname followed by a list of commits:
+You want to reverse the order git rev-list emits because it lists
+from most recent to oldest.
+
+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
better documented. The shell version is maintained only as a fallback
for use on hosting sites that don't permit Python hook scripts.
-You will find installation instructions for each script in its comment
-header.
+See the file INSTALL for installation instructions.
# usage: ciabot.py [-V] [-n] [-p projectname] [refname [commits...]]
#
# This script is meant to be run either in a post-commit hook or in an
-# update hook. If there's nothing unusual about your hosting setup,
-# you can specify the project name and repo with config variables and
-# avoid having to modify this script. Try it with -n to see the
-# notification mail dumped to stdout and verify that it looks
-# sane. With -V it dumps its version and exits.
+# update hook. Try it with -n to see the notification mail dumped to
+# stdout and verify that it looks sane. With -V it dumps its version
+# and exits.
#
# In post-commit, run it without arguments. It will query for
# current HEAD and the latest commit ID to get the information it
# /path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
#
# Configuration variables affecting this script:
-# ciabot.project = name of the project (required)
+#
+# ciabot.project = name of the project
# ciabot.repo = name of the project repo for gitweb/cgit purposes
# ciabot.xmlrpc = if true (default), ship notifications via XML-RPC
# ciabot.revformat = format in which the revision is shown
#
-# The ciabot.repo value defaults to ciabot.project lowercased.
+# ciabot.project defaults to the directory name of the repository toplevel.
+# ciabot.repo defaults to ciabot.project lowercased.
+#
+# This means that in the normal case you need not do any configuration at all,
+# but setting the project name will speed it up slightly.
#
# The revformat variable may have the following values
# raw -> full hex ID of commit
# Identify the generator script.
# Should only change when the script itself gets a new home and maintainer.
generator = "http://www.catb.org/~esr/ciabot.py"
-version = "3.5"
+version = "3.6"
def do(command):
return commands.getstatusoutput(command)[1]
print "ciabot.py: version", version
sys.exit(0)
- # Cough and die if user has not specified a project
+ # The project variable defaults to the name of the repository toplevel.
if not project:
- sys.stderr.write("ciabot.py: no project specified, bailing out.\n")
- sys.exit(1)
+ here = os.getcwd()
+ while True:
+ if os.path.exists(os.path.join(here, ".git")):
+ project = os.path.basename(here)
+ break
+ elif here == '/':
+ sys.stderr.write("ciabot.py: no .git below root!\n")
+ sys.exit(1)
+ here = os.path.dirname(here)
if not repo:
repo = project.lower()
# usage: ciabot.sh [-V] [-n] [-p projectname] [refname commit]
#
# This script is meant to be run either in a post-commit hook or in an
-# update hook. If there's nothing unusual about your hosting setup,
-# you can specify the project name and repo with config variables and
-# avoid having to modify this script. Try it with -n to see the
-# notification mail dumped to stdout and verify that it looks
-# sane. With -V it dumps its version and exits.
+# update hook. Try it with -n to see the notification mail dumped to
+# stdout and verify that it looks sane. With -V it dumps its version
+# and exits.
#
# In post-commit, run it without arguments. It will query for
# current HEAD and the latest commit ID to get the information it
# most recent to least - better to ship notifactions from oldest to newest.
#
# Configuration variables affecting this script:
-# ciabot.project = name of the project (makes -p option unnecessary)
+#
+# ciabot.project = name of the project
# ciabot.repo = name of the project repo for gitweb/cgit purposes
# ciabot.revformat = format in which the revision is shown
#
-# The ciabot.repo defaults to ciabot.project lowercased.
+# ciabot.project defaults to the directory name of the repository toplevel.
+# ciabot.repo defaults to ciabot.project lowercased.
+#
+# This means that in the normal case you need not do any configuration at all,
+# but setting the project name will speed it up slightly.
#
# The revformat variable may have the following values
# raw -> full hex ID of commit
# shpped from an update in their actual order.)
#
-# The project as known to CIA. You can also hardwire this or set it with a
-# -p option.
+# The project as known to CIA. You can set this with a -p option,
+# or let it default to the directory name of the repo toplevel.
project=$(git config --get ciabot.project)
+if [ -z $project ]
+then
+ here=`pwd`;
+ while :; do
+ if [ -d $here/.git ]
+ then
+ project=`basename $here`
+ break
+ elif [ $here = '/' ]
+ then
+ echo "ciabot.sh: no .git below root!"
+ exit 1
+ fi
+ here=`dirname $here`
+ done
+fi
+
# Name of the repo for gitweb/cgit purposes
repo=$(git config --get ciabot.repo)
[ -z $repo] && repo=$(echo "${project}" | tr '[A-Z]' '[a-z]')
# Identify the script. The 'generator' variable should change only
# when the script itself gets a new home and maintainer.
generator="http://www.catb.org/~esr/ciabot/ciabot.sh"
-version=3.4
+version=3.5
# Addresses for the e-mail
from="CIABOT-NOREPLY@${hostname}"
else
echo "perf $test_count - $1:"
fi
- for i in $(seq 1 $GIT_PERF_REPEAT_COUNT); do
+ for i in $(test_seq 1 $GIT_PERF_REPEAT_COUNT); do
say >&3 "running: $2"
if test_run_perf_ "$2"
then
test_expect_success EXPENSIVE 'create 50,000 tags in the repo' '
(
cd "$HTTPD_DOCUMENT_ROOT_PATH/repo.git" &&
- for i in `seq 50000`
+ for i in `test_seq 50000`
do
echo "commit refs/heads/too-many-refs"
echo "mark :$i"
$GIT_TEST_CMP "$@"
}
+# Print a sequence of numbers or letters in increasing order. This is
+# similar to GNU seq(1), but the latter might not be available
+# everywhere (and does not do letters). It may be used like:
+#
+# for i in `test_seq 100`; do
+# for j in `test_seq 10 20`; do
+# for k in `test_seq a z`; do
+# echo $i-$j-$k
+# done
+# done
+# done
+
+test_seq () {
+ case $# in
+ 1) set 1 "$@" ;;
+ 2) ;;
+ *) error "bug in the test script: not 1 or 2 parameters to test_seq" ;;
+ esac
+ "$PERL_PATH" -le 'print for $ARGV[0]..$ARGV[1]' -- "$@"
+}
+
# This function can be used to schedule some commands to be run
# unconditionally at the end of the test to restore sanity:
#