[0/3] Branches are branches and not heads

Message

Junio C Hamano June 3, 2024, 8:05 p.m. UTC

Back when Git started, we used the word "head" to mean the tip of
possibly multiple histories, and that is where the name of the
hierarchy .git/refs/heads/ came from.  But these days we call these
entities "branches" in human terms, and "head" is still used to
refer to the tip of the history each of these branches represent.

When asking "git ls-remote" or "git show-ref" to limit their output
to branches (as opposed to showing any ref), we use "--heads" for
historical reasons, but give the option a more human friendly name
"--branches", and demote "--heads" to the status of a deprecated
synonym.  This would eventually allow us to remove them at the
breaking version boundary.

Junio C Hamano (3):
  refs: call branches branches
  ls-remote: introduce --branches and deprecate --heads
  show-ref: introduce --branches and deprecate --heads

 Documentation/git-ls-remote.txt | 12 +++++++-----
 Documentation/git-show-ref.txt  | 18 ++++++++++--------
 builtin/ls-remote.c             | 25 ++++++++++++++++++++++---
 builtin/show-ref.c              | 33 ++++++++++++++++++++++++++-------
 connect.c                       |  4 ++--
 remote.h                        |  2 +-
 t/t1403-show-ref.sh             | 22 ++++++++++++++--------
 t/t5512-ls-remote.sh            | 30 +++++++++++++++++++++++++-----
 8 files changed, 107 insertions(+), 39 deletions(-)

Comments

Rubén Justo June 3, 2024, 9:32 p.m. UTC | #1

On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:
> Back when Git started, we used the word "head" to mean the tip of
> possibly multiple histories, and that is where the name of the
> hierarchy .git/refs/heads/ came from.  But these days we call these
> entities "branches" in human terms, and "head" is still used to refer
> to the tip of the history each of these branches represent.
> 
> When asking "git ls-remote" or "git show-ref" to limit their output to
> branches (as opposed to showing any ref), we use "--heads" for
> historical reasons, but give the option a more human friendly name
> "--branches", and demote "--heads" to the status of a deprecated
> synonym.  This would eventually allow us to remove them at the
> breaking version boundary.

All of this sounds like a very sensible step, to me.

I've left a couple of nits;  none important. 

Thanks.

> 
> Junio C Hamano (3):
>   refs: call branches branches
>   ls-remote: introduce --branches and deprecate --heads
>   show-ref: introduce --branches and deprecate --heads
> 
>  Documentation/git-ls-remote.txt | 12 +++++++-----
>  Documentation/git-show-ref.txt  | 18 ++++++++++--------
>  builtin/ls-remote.c             | 25 ++++++++++++++++++++++---
>  builtin/show-ref.c              | 33 ++++++++++++++++++++++++++-------
>  connect.c                       |  4 ++--
>  remote.h                        |  2 +-
>  t/t1403-show-ref.sh             | 22 ++++++++++++++--------
>  t/t5512-ls-remote.sh            | 30 +++++++++++++++++++++++++-----
>  8 files changed, 107 insertions(+), 39 deletions(-)
> 
> -- 
> 2.45.2-404-g9eaef5822c
>

Patrick Steinhardt June 4, 2024, 7:56 a.m. UTC | #2

On Mon, Jun 03, 2024 at 11:32:18PM +0200, Rubén Justo wrote:
> On Mon, Jun 03, 2024 at 01:05:36PM -0700, Junio C Hamano wrote:
> > Back when Git started, we used the word "head" to mean the tip of
> > possibly multiple histories, and that is where the name of the
> > hierarchy .git/refs/heads/ came from.  But these days we call these
> > entities "branches" in human terms, and "head" is still used to refer
> > to the tip of the history each of these branches represent.
> > 
> > When asking "git ls-remote" or "git show-ref" to limit their output to
> > branches (as opposed to showing any ref), we use "--heads" for
> > historical reasons, but give the option a more human friendly name
> > "--branches", and demote "--heads" to the status of a deprecated
> > synonym.  This would eventually allow us to remove them at the
> > breaking version boundary.
> 
> All of this sounds like a very sensible step, to me.
> 
> I've left a couple of nits;  none important. 

Agreed, I like the direction of this patch series very much. I've got
nothing to add on top of what has already been said.

Thanks!

Patrick