1

I'm trying to denote Git branches from contributing users with the ~ tilde sign similar to the notation used to refer to home folders on UNIX-like operating systems but Git prevents me from doing so in that it aborts branch creation with the error message fatal: '~' is not a valid branch name. The branch names from contributors should look like ~alice/feature/foo, ~bob/bugfix/bar etc.

None of the following commands work with Git version 2.14.1:

$ git checkout -b '~'
fatal: '~' is not a valid branch name.
$ git checkout -b '~bar'
fatal: '~bar' is not a valid branch name.
$ git checkout -b 'foo~'
fatal: 'foo~' is not a valid branch name.
$ git checkout -b 'foo~bar'
fatal: 'foo~bar' is not a valid branch name.

For the moment as an alternate denotation I have decided on the @ at sign as the common prefix for my purposes. But I'm rethinking the decision of making rather unusual characters part of my branch names other than the - hyphen and _ underscore signs as word delimiters due to possible restrictions that may be imposed by Git itself or the underlying filesystem a Git repository happens to be e.g. checked out and thus stored on.

Tim Friske
  • 2,012
  • 1
  • 18
  • 28
  • Duplicate question link needs to be reviewed once more. The branch name in git is actually a folder. ~ means home directory in unix systems. So, that folder already exists, hence git is unable to make such a branch. This Q&A have some detail https://stackoverflow.com/questions/2527355/using-the-slash-character-in-git-branch-name/2527452#2527452 –  Aug 28 '17 at 17:11
  • @Eyorther `~` is a perfectly suitable directory name in linux. `mkdir \~` works like a charm. – YSC Aug 28 '17 at 17:14
  • 1
    @CodeCaster I voted to reopen this question since: 1/ I put some effort in answering to it with information not present on the proposed duplicate and 2/ this is not a perfect duplicate: OP asks why it is forbidden, not if it is forbidden. – YSC Aug 28 '17 at 17:17
  • @YSC mkdir ~ and mkdir /~, there is a difference. The later one makes a directory ~ in root folder. –  Aug 28 '17 at 17:17
  • @Eyorther The tilde name of your home directory is a shorthand managed by your shell, not by the system nor the kernel. `mkdir \~` will make the shell ignore the tilde and pass as first argument to `mkdir` the name `~` _as is_. `mkdir` is perfectly capable of creating a directory named `~`. It means nothing to him (it?). – YSC Aug 28 '17 at 17:20
  • I reopened this as requested, but want to put the link back in (StackOverflow auto-removed it): https://stackoverflow.com/questions/3651860/which-characters-are-illegal-within-a-branch-name – torek Aug 28 '17 at 17:57

2 Answers2

5

A git reference (tag or branch) is forbidden to contain a tilde (~) since this character is used to refer to a parent commit:

  • ref~ is a shorthand for ref~1 and means ref's first parent;
  • ref~2 means ref's second parent;
  • ...

Check out Paul Boxley's Git caret and tilde article for a quick summary of the role of the tilde and caret (^) in git syntax.

Finally, you'll find all the documentation about git syntax for refering to commit in the official documentation.

YSC
  • 38,212
  • 9
  • 96
  • 149
  • I think the OP doesn't like the answer (even though it's correct). It may not be a *great* reason as I note in comment on my answer, but it *is* the (original) reason. – torek Aug 28 '17 at 17:47
2

The rules for reference names are given in the git check-ref-format manual page. The tilde ~, carat ^, and colon : characters are forbidden since they are syntactic items when parsing references: master~3 means count back three first parents from the commit to which master points, for instance, and HEAD:path/to/blob is a file (blob) within the current commit.

torek
  • 448,244
  • 59
  • 642
  • 775
  • But then again if Git were very strict about special characters in branch names why doesn't it forbid the `@` *at* sign since `@` is short for the symbolic reference `HEAD`? – Tim Friske Aug 28 '17 at 17:29
  • 2
    In fact `@`-as-a-whole *is* forbidden (rule 9) and `@{` is also forbidden (rule 8). The rules *could* be relaxed to forbid only `~` followed by digits (or end of string), since `this~that` has no defined meaning, only `this~`. However, Git seems to be going in the other direction (adding more restrictions) at the moment, probably because of Windows. – torek Aug 28 '17 at 17:36