Hacker News Reader

Comment by beeforpork | Hacker News Reader

> git init --bare

Aha, '--bare': what does that do? I always just type 'git init'.

Let me do a little git bashing, OK? Sorry for this, but it so nicely documents my initial problems with git when I started a few years back. And it still occasionally (like right now) makes me shake my head in disbelief:

> man git-init

Searching for --bare gives me:

> --bare

> Create a bare repository. ...and how GIT_DIR is set...

You don't say!!

I search for other occurrences of 'bare' in that man page, but after skipping those in the synopsis and the help text, it says:

> Pattern not found

So bare = bare. Tautological documentation. It's all obvious, right?

What --bare really does is to put what git would normally put into the '.git' subdir into '.'. I tried what it does, that's how I found out.

Git is great, but please never claim that it is intuitively documented.

View on HN

The man pages are indeed not great. I usually invest a bit more time reading the git book, it explains what a bare repo is a bit better: “ a new bare repository — a repository that doesn’t contain a working directory.” From the “setting up git on a server” chapter (https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git...) which I think is the main reason why one would use a bare repo.

That said I concur and don’t think anyone would make such a claim about git documentation.

If all else fails, try https://git-man-page-generator.lokaltog.net/ :)

Here's the very short answer:

A bare repo has only Git's own data structure files. It's basically the contents of a non-bare repo's ".git/" directory, without a checked out working copy of all the files that are contained in the repo. The files are all still there but stored inside Git's database and not in the filesystem in the normal way.

The advantage: you can push commits to a bare repo. It's the kind of repo you'd put on your remote dev server. If you try to push to a non-bare repo, you'd get an error message like:

  remote: error: refusing to update checked out branch: refs/heads/dev
  remote: error: By default, updating the current branch in a non-bare repository
  remote: is denied, because it will make the index and work tree inconsistent
  remote: with what you pushed, and will require 'git reset --hard' to match
  remote: the work tree to HEAD.

...which is a long way of saying "don't do that". The disadvantage is that you can't cd into a bare repo and use "ls" and friends to browse around.

So here's the even shorter answer:

Make a bare repo when you only want to push to it but not work inside it, say because you're making a shared repo for you and your friends to work on together.

Make a non-bare repo when you want to work inside it but not push to it, say because it's a project you're developing on your laptop.

This is as short as I can make my understanding of what you are saying:

A bare git repo is a server side git repo while non-bare is client side.

Nailed it.

git user interface design is a disaster. It's no wonder it's hard to document (this is a bit orthogonal to your point...).

Git has an extremely complex data structure/state: It's a forest of DAGs (commits in distributed repos), with labels on them (branches), that have specified relationships (remotes), as well as an index and a stash per DAG. All of this on top of the working directory (and .gitignore if you want).

Of course these individual elements are mostly necessary to enable complex workflows. But simple workflows interact with all of these elements too in complex ways. This complexity is neither hidden behind a sensible set of UX abstractions, nor are they cleanly exposed to the user with a set of clean elementary operations to work on them...

Mercurial works more or less the same way, and yet I find mercurial UI much simpler.

The main difference, I think, is that mercurial has stronger opinions on how you should manage your repository and hides everything that doesn't fit its views behind extensions.

Really, I don't understand how git managed to become so popular. It is really good and I like it a lot but it really takes time getting used to. I screwed up a lot before getting competent with it, and I still screw up from time to time. It didn't happen with cvs, svn and mercurial.

It makes me think of Perl. Powerful and messy, I like if for the same reason I like git. But while Perl is on the way down, progressively replaced by cleaner, more opinionated alternatives, git is becoming a de-facto standard.

I’ve always believed that it was GitHub that allowed git to win out.

In addition to that, I suspect it was the very fact that Mercurial had more features, specifically an in built web server that allowed you to easily share your repo, led to GitHub being created with git and not mercurial.

The way I look at it, Mercurial made it extremely easy to self host a repo. So there was no need for a 3rd party centralized service to share your mercurial repo. That wasn’t the case for git, so something like GitHub was needed.

But the centralization in GitHub also allowed them to add more social features, which allowed git to spread more widely.

It’s almost like git was written by kernel programmers who knew only C and Perl.

[Shameless plug] If all you need is the ability to manage a bunch of personal repositories hosted on your ssh server, you may want to try "reposetup", a minimalist, shell-based, repository manager: https://github.com/agateau/reposetup

While that is true, I did try searching the main git man page for GIT_DIR and found it said the following:

> GIT_DIR

> If the GIT_DIR environment variable is set then it specifies a path to use instead of the default .git for the base of the repository. The --git-dir command-line option also sets this value.

That said, manuals are typically written like this, meaning that for terms one isn't already aware of, there is a need to search through the index to find its meaning and them piece together the information.

> git init --help > OPTIONS > --bare > Create a bare repository. If GIT_DIR environment is not set, it is set to the current working directory.

I'm confused on what you find confusing here?

> git init --help > OPTIONS > --tiramisu > Create a tiramisu repository. If GIT_DIR environment is not set, it is set to the current working directory.

Ok, so can you tell me what is a tiramisu repository?

If the directory containing the git objects is not set, it is set to use the directory you normally find a working tree in. This is pretty straightforward once you know the basics of git, and I can’t imagine anyone would be creating a repo holding only the objects (a remote only repo you simply pull/push to/from) until they know the basics of git.

Are you saying you don't know what the word "bare" means? Is that the confusion?

Googling for the definition I find "Bare: without addition; basic and simple."

And yes, I can. A tiramisu repository is a fictional repository that is not at all mentioned the very helpful help section of git init. While completely fabricated, the tiramisu repository is one of the best tasting repositories git can produce.

This is the exact point the parent post makes. You have to google what the hell is a bare git repository. It is not intuitive or clearly documented.

git is split up in many man pages. That's generally a good thing, but you sometimes have to search or look at more than one man page to find what you are looking for.

You could try

> man -K "bare repo"

to search all man pages for that string, and you'll find that

> man git-clone

has the information you are looking for:

"--bare: Make a bare Git repository. That is, instead of creating <directory> and placing the administrative files in <directory>/.git, make the <directory> itself the $GIT_DIR. This obviously implies the -n because there is nowhere to check out the working tree."

If you have Internet connectivity, Google is also an option. Among the first hits should be the book "Pro Git", chapter "4.2 Git on the Server", which begins with a concise explanation what a bare repository is.

> ... but you sometimes have to search or look at more than one man page to find what you are looking for.

Well, yes, that's one of the problems. I am saying the docs are unintuitive, and now you are confirming that.

For 'git init --bare', I look into 'git-init' and search for '--bare'. That's what I do, that's intuitive to me. And that's not where the info is. Is all I am saying.

Reply on news.ycombinator.com