Git Branch

名称

git-branch - 列出、创建或删除分支(List, create, or delete branches)

语法

git branch [--color[=<when>] | --no-color] [--show-current]
        [-v [--abbrev=<n> | --no-abbrev]]
        [--column[=<options>] | --no-column] [--sort=<key>]
        [--merged [<commit>]] [--no-merged [<commit>]]
        [--contains [<commit>]] [--no-contains [<commit>]]
        [--points-at <object>] [--format=<format>]
        [(-r | --remotes) | (-a | --all)]
        [--list] [<pattern>…​]
git branch [--track | --no-track] [-f] <branchname> [<start-point>]
git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
git branch --unset-upstream [<branchname>]
git branch (-m | -M) [<oldbranch>] <newbranch>
git branch (-c | -C) [<oldbranch>] <newbranch>
git branch (-d | -D) [-r] <branchname>…​
git branch --edit-description [<branchname>]

如果给出了--list，或者没有非选项参数，则列出现有分支；当前分支将以绿色突出显示并用星号标记。链接工作树中签出的任何分支都将以青色突出显示并用加号标记。选项-r会列出远程跟踪分支，选项-a会显示本地和远程分支。

如果给出了<pattern>，则将其用作shell通配符以将输出限制为匹配的分支。如果给出了多个模式，则如果分支与任何模式匹配，则会显示一个分支。

请注意，在提供<pattern>时，您必须使用--list；否则该命令可能会被解释为分支创建。

使用 --contains 时，只显示包含命名提交的分支（换句话说，其尖端提交是命名提交的后代）， --no-contains包含将其反转。使用--merged 时，将只列出合并到命名提交的分支（即其HEAD提交可从命名提交访问的分支）。使用--no-merged时，将只列出未合并到命名提交的分支。如果缺少<commit>参数，则默认为HEAD（即当前分支的HEAD）。

该命令的第二种形式创建了一个新的分支头，名为<branch-name>，它指向当前HEAD，如果给定，则指向<star-point>。作为特殊情况，对于<star-point>，如果A和B的合并基正好有一个，您可以使用“A… B”作为合并基的快捷方式。您最多可以省略A和B中的一个，在这种情况下，它默认为HEAD。 请注意，这将创建新分支，但不会将工作树切换到它；使用“git switch<new-branch>”切换到新分支。

当本地分支从远程跟踪分支启动时，Git设置分支（特别是branch..remote 和 branch..merge配置条目），以便git拉将适当地从远程跟踪分支合并。此行为可以通过全局branch.autoSetupMerge配置标志更改。该设置可以通过使用--track和--no-track选项覆盖，稍后使用git分支--set-upry-to进行更改。

使用-m或-M选项，<oldbranch>将被重命名为<newbranch>。如果<oldbranch>有相应的重新命名，则将其重命名为与<newbranch>匹配，并创建一个重新命名条目以记住分支重命名。如果<newbranch>存在，则必须使用-M来强制重命名。

-c和-C选项与-m和-M具有完全相同的语义学，只是它不会被重命名，而是会被复制到一个新名称，以及它的配置和重新命名。

使用-d或-D选项，<Branchname>将被删除。您可以指定多个要删除的分支。如果该分支当前有重新启动，则重新启动也将被删除。

使用-r和-d删除远程跟踪分支。请注意，只有当远程存储库中不再存在远程跟踪分支或git fetch配置为不再获取它们时，删除远程跟踪分支才有意义。另请参阅git-Remote（1）的prune子命令，了解清理所有过时远程跟踪分支的方法。

使用

• -a/--all 列出远程跟踪分支和本地分支。与--list组合以匹配可选模式。

• -l/--list 列出分支。使用可选的<模式>…，例如git分支--list'维护-*'，仅列出与模式匹配的分支。

• --show-current 显示当前分支

• --column和--no-column 在列中显示分支列表。有关选项语法，请参见配置变量column.branch。没有选项的 --column 和 --no-column分别等效于始终和从不。此选项和-v/--verbose不能同时使用。

• -v/-vv / --verbose 在列表模式下，为每个头显示sha1和提交主题行，以及与上游分支的关系（如果有）。如果给出两次，请打印链接工作树的路径（如果有）和上游分支的名称。请注意，当前工作树的HEAD不会打印其路径（它将始终是您的当前目录）。

  ## 项目当前分支状态/列出所有分支
  $ git branch -a /$ git branch -l -a 
    dev
  * main
    relea
    remotes/origin/HEAD -> origin/main
    remotes/origin/dev
    remotes/origin/main
    remotes/origin/relea
  $ git branch   --show-current
  main
  $ git branch -l   --column
    dev     local      * main         relea
  $ git branch -l   --no-column
    dev
    local
  * main
    relea
  ##  使用另一个更接近生产的项目
  $ git branch -v 
    Java-Agent                3491522 agent
  + Linux                     199a44d 文件复制
    activiti                  cc4d8b2 [behind 1] 通过表结构和Json生成修改注释的Sql
    algorithms 				0331092 data
  ## 打印worktree,上游分支的名称
  $ git branch -vv 
    Java-Agent  3491522 [origin/Java-Agent] agent
  + Linux       199a44d (D:/JavaWorkSpace/linux-comprehensive) [origin/Linux] 文件复制
    activiti    cc4d8b2 [origin/activiti: behind 1] 修改注释的Sql
    algorithms  0331092 [origin/datastructures-algorithms] data
  

• -c/--copy 复制一个分支和相应的reflog.

• -C 强制复制的快捷方式。等效 --copy --force.

  $ git branch -vv
    dev   26e602f [origin/dev] dev commit
    local 9df539e main file
  * main  9df539e [origin/main] main file
    relea c76aaf9 [origin/relea] rele
  ## 分别使用几种不同的方式新建分支 -c/--copy 从main新建一个分支，当前分支为main
  $ git branch -c new_brach_whit-c
  $ git branch new_branch
  $ git branch new_branch_from-head  HEAD
  $ git branch new_branch_from-dev  dev
  $ git branch --track  new_branch_from-relea  relea 
  Branch 'new_branch_from-relea' set up to track local branch 'relea'.
  $ git branch --track  new_branch_from-local local 
  Branch 'new_branch_from-local' set up to track local branch 'local'.
  $ git branch -c  --track  new_branch_from_relea_with-c   relea
  fatal: A branch named 'relea' already exists.
  $ git branch -c  --track  new_branch_from_local_with_c   local 
  fatal: A branch named 'local' already exists.
  ## 查看当前配置仓库branch配置， -c
  $ git config --list |grep new_bran 
  branch.new_brancch_whit-c.remote=origin
  branch.new_brancch_whit-c.merge=refs/heads/main    
  branch.new_branch_from-relea.remote=.
  branch.new_branch_from-relea.merge=refs/heads/relea
  branch.new_branch_from-local.remote=.
  branch.new_branch_from-local.merge=refs/heads/local
  ## -c会复制上游分支，否则只是复制分支，不显示指定目录分支即为当前HEAD，-c  --track 不能同时使用
  $ git branch -vv -l  new_b*
    new_brancch_whit-c    9df539e [origin/main] main file
    new_branch            9df539e main file
    new_branch_from-dev   26e602f dev commit
    new_branch_from-head  9df539e main file
    new_branch_from-relea c76aaf9 [relea] rele
  

• -d/--delete删除分支。该分支必须完全合并到其上游分支中，如果没有使用--track或--set-upstream-to设置上游，则必须完全合并到HEAD中。

• -D 强制删除的快捷方式。等效 --delete --force.

• -r/--remotes 列出或删除（如果与-d一起使用）远程跟踪分支。与“--list”组合以匹配可选模式。

  ##　删除分支dev relea 
  $ git branch -d dev relea 
  Deleted branch dev (was 26e602f).  
  Deleted branch relea (was c76aaf9).
  $ git branch -vv 
    local                 9df539e main file
  * main                  9df539e [origin/main] main file
    new_brancch_whit-c    9df539e [origin/main] main file
    new_branch            9df539e main file
    new_branch_from-dev   26e602f dev commit
    new_branch_from-head  9df539e main file
    new_branch_from-local 9df539e [local] main file
    new_branch_from-relea c76aaf9 [relea: gone] rele
  ## 删除所有本地分支后
  $ git branch -vv -a 
  * main                 9df539e [origin/main] main file
    remotes/origin/HEAD  -> origin/main
    remotes/origin/dev   26e602f dev commit
    remotes/origin/main  9df539e main file
    remotes/origin/relea c76aaf9 rele
  ## 删除远程分支，其实并没有实际删除远程仓库的分支
  $ git branch -vv -r  -d origin/relea 
  Deleted remote-tracking branch origin/relea (was c76aaf9).
  ## 重新fetch远程分支
  $ git fetch 
  From http://gitlab.jinkosolar.com/user/testgit
   * [new branch]      relea      -> origin/relea
  $ git branch -vv  -a
  * main                 9df539e [origin/main] main file
    remotes/origin/HEAD  -> origin/main
    remotes/origin/dev   26e602f dev commit
    remotes/origin/main  9df539e main file
    remotes/origin/relea c76aaf9 rele
  

• -t/--track 当创建一个新分支时，设置branch.<name>. Remote和branch.<name>.merge配置条目，将起始点分支标记为从新分支的“上游”。此配置将告诉git在git status和git branch -v中显示两个分支之间的关系。此外，当新分支被签出时，它会指示不带参数的git拉从上游拉取。

  当起始点是远程跟踪分支时，此行为是默认的。如果您希望git switch、git checkout和git branch始终表现得像给出了--no-track一样，请将branch.autoSetupMerge配置变量设置为false。如果您希望起始点是本地或远程跟踪分支时出现此行为，请将其设置为始终。

• --no-track 不要设置“上游”配置，即使branch.autoSetupMerge配置变量为真。

  要理解--track和上游分支，可以先看完跟踪分支

  ##  git branch local 从main新建一个本地分支local,并提交一个commit后。
  $ git branch -vv -a
    local                2cb97cf local commit
  * main                 9df539e [origin/main] main file
    remotes/origin/HEAD  -> origin/main
    remotes/origin/dev   26e602f dev commit
    remotes/origin/main  9df539e main file
    remotes/origin/relea c76aaf9 rele
  ## 从远程分支新建一个分支
  $ git branch --track dev  origin/dev
  Branch 'dev' set up to track remote branch 'dev' from 'origin'.
  ## 当起始点是远程跟踪分支时，此行为是默认的.即默认会添加 --track
  $ git branch relea origin/relea
  Branch 'relea' set up to track remote branch 'relea' from 'origin'.
  ## 查看配置文件，去掉了一些无需关注的配置
  $ cat .git/config 
  [remote "origin"]
          url = http://gitlab.jinkosolar.com/yuansheng.xu/testgit.git
          fetch = +refs/heads/*:refs/remotes/origin/*
  [branch "main"]
          remote = origin
          merge = refs/heads/main
  [branch "dev"]
          remote = origin
          merge = refs/heads/dev
  [branch "relea"]
          remote = origin
          merge = refs/heads/relea
  ## 从本地分支新建一个分支
  $ git branch  from_local local 
  $ git branch  --track  from_local_track local
  Branch 'from_local_track' set up to track local branch 'local'.
  $ git branch --no-track  from_remote_dev_no_track origin/dev
  ## 查看配置文件，去掉了一些无需关注的配置
  $ cat .git/config |grep from_local -A 2
  [branch "from_local_track"]
          remote = .
          merge = refs/heads/local
  

• -u/--set-upstream-to=<upstream> 设置<Branch-name>的跟踪信息，以便将upstream视为Branch的上游分支。如果未指定<Branch-name>，则默认为当前分支。

• --unset-upstream 删除<分支名称>的上游信息。如果未指定分支，则默认为当前分支。

  ## 将上一个例子中没有设置的上游添加上
  $ git branch -u dev from_remote_dev_no_track
  Branch 'dev' set up to track local branch 'from_remote_dev_no_track'.
  $ cat .git/config |grep from_ -A 2
  [branch "from_local_track"]
          remote = .
          merge = refs/heads/local   
  [branch "from_remote_dev_no_track"]
          remote = .
          merge = refs/heads/dev
  ## 将分支 from_local_track 的上游删除
  $ git branch --unset-upstream from_local_track
  $  cat .git/config |grep from_ -A 2
  [branch "from_remote_dev_no_track"]
          remote = .
          merge = refs/heads/dev
  ## 删除当前HEAD所指向分支的上游，不想删除main分支的上游，切换到分支from_remote_dev_no_track
  $ git checkout from_remote_dev_no_track
  $ git branch --unset-upstream
  $ cat .git/config |grep from_ -A 2 
  $ cat .git/config |grep branch -A 2
  [branch "main"]
          remote = origin
          merge = refs/heads/main
  [branch "dev"]
          remote = origin
          merge = refs/heads/dev
  [branch "relea"]
          remote = origin
          merge = refs/heads/relea
  ## 将本地分支local的上游分支设置为本地的另一个分支dev
  ## 当前提交历史
  $ git log dev local  --graph  --pretty=oneline 
  * 2cb97cf0938ee88aa11e6b28af376546c2a85c0a (HEAD -> local) local commit
  * 9df539ee86586d32d4349aa19e235941926cefec (origin/main, origin/HEAD, main) main file
  | * 26e602f538ab6a74ac985853690136e064cbe172 (origin/dev, dev) dev commit
  | * 1d40930975eaeef50830c457bdcd7811db6ef173 first main commit
  |/
  * a94823afd688061ad02285591fb36a7dbeb520dd Initial commit
  $ git branch -vv
    dev   26e602f [origin/dev] dev commit
  * local 2cb97cf local commit
    main  9df539e [origin/main] main file
    relea c76aaf9 [origin/relea] rele
  ## 设置上游分支，配置中本地dev分支的上游分支为远程仓库的dev分支，local分支的上游是本地dev分支
  $ git branch -u dev local 
  Branch 'local' set up to track local branch 'dev'.
  $ cat .git/config |grep heads/dev  -B 2
  [branch "dev"]
          remote = origin
          merge = refs/heads/dev
  --
  [branch "local"]
          remote = .
          merge = refs/heads/dev
  ## 再看local的状态，发现有 "[dev: ahead 2, behind 2]"，说明本地分支lcoal有两个提交没有合并到本地分支dev中，dev中也有两个提交没有合并到local中
  $ git branch -vv
    dev   26e602f [origin/dev] dev commit
  * local 2cb97cf [dev: ahead 2, behind 2] local commit
    main  9df539e [origin/main] main file
    relea c76aaf9 [origin/relea] rele
  ## 此时执行 git pull 会中本地分支dev中拉取提交(效果类比远程分支)
  $ git pull 
  From .
   * branch            dev        -> FETCH_HEAD
  Merge made by the 'recursive' strategy.
   README.md | 93 +--------------------------------------------------------------
   dev.txt   |  1 +
   2 files changed, 2 insertions(+), 92 deletions(-)
   create mode 100644 dev.txt
  

• --edit-description

  打开编辑器并编辑文本以解释分支的用途，以供各种其他命令使用（例如格式化补丁、请求拉取和合并（如果启用））。可以使用多行解释。

• --contains []

  仅列出包含指定提交的分支（如果未指定HEAD）。暗示--list。

• --no-contains []

  仅列出不包含指定提交的分支（如果未指定HEAD）。暗示--list。

• --merged []

  仅列出可从指定提交（如果未指定HEAD）访问其提示的分支。暗示--list。

• --no-merged []

  仅列出其提示无法从指定提交（如果未指定HEAD）访问的分支。暗示--list

  $ git branch -vv
    dev                      26e602f [origin/dev] dev commit
    from_local               2cb97cf local commit
    from_local_track         2cb97cf local commit
    from_remote_dev_no_track 26e602f dev commit
    local                    2cb97cf local commit
  * main                     9df539e [origin/main] main file
    relea                    c76aaf9 [origin/relea] rel
  $ git branch --contains 26e602f 
    dev
    from_remote_dev_no_track
    relea
  $ git branch --no-contains 26e602f
    from_local
    from_local_track
    local
  * main
  $ git branch --merged 2cb97cf 
    from_local
    from_local_track
    local
  * main
  $ git branch --no-merged 2cb97cf
    dev
    from_remote_dev_no_track
    relea