From de90ff81f3bba50776b934842112eeb6e69a0d23 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 31 Jan 2013 01:45:46 -0500 Subject: docs: clarify git-branch --list behavior It was not clear from the "description" section of git-branch(1) that using a meant that you _had_ to use the --list option. Let's clarify that, and while we're at it, reword some clunky and ambiguous sentences. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-branch.txt | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'Documentation/git-branch.txt') diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 45a225e0aa..2635dee413 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -22,13 +22,15 @@ SYNOPSIS DESCRIPTION ----------- -With no arguments, existing branches are listed and the current branch will -be highlighted with an asterisk. Option `-r` causes the remote-tracking -branches to be listed, and option `-a` shows both. This list mode is also -activated by the `--list` option (see below). - restricts the output to matching branches, the pattern is a shell -wildcard (i.e., matched using fnmatch(3)). -Multiple patterns may be given; if any of them matches, the branch is shown. +If `--list` is given, or if there are no non-option arguments, existing +branches are listed; the current branch will be highlighted with an +asterisk. Option `-r` causes the remote-tracking branches to be listed, +and option `-a` shows both local and remote branches. If a `` +is given, it is used as a shell wildcard to restrict the output to +matching branches. If multiple patterns are given, a branch is shown if +it matches any of the patterns. Note that when providing a +``, you must use `--list`; otherwise the command is interpreted +as branch creation. With `--contains`, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the -- cgit v1.2.1 From d040350813986e0f4bb3aeb977077975c1552606 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 31 Jan 2013 01:46:11 -0500 Subject: branch: let branch filters imply --list Currently, a branch filter like `--contains`, `--merged`, or `--no-merged` is ignored when we are not in listing mode. For example: git branch --contains=foo bar will create the branch "bar" from the current HEAD, ignoring the `--contains` argument entirely. This is not very helpful. There are two reasonable behaviors for git here: 1. Flag an error; the arguments do not make sense. 2. Implicitly go into `--list` mode This patch chooses the latter, as it is more convenient, and there should not be any ambiguity with attempting to create a branch; using `--contains` and not wanting to list is nonsensical. That leaves the case where an explicit modification option like `-d` is given. We already catch the case where `--list` is given alongside `-d` and flag an error. With this patch, we will also catch the use of `--contains` and other filter options alongside `-d`. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-branch.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-branch.txt') diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 2635dee413..597d64ec1f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -195,15 +195,15 @@ start-point is either a local or remote-tracking branch. --contains []:: Only list branches which contain the specified commit (HEAD - if not specified). + if not specified). Implies `--list`. --merged []:: Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified). Implies `--list`. --no-merged []:: Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified). Implies `--list`. :: The name of the branch to create or delete. -- cgit v1.2.1