67d9b39cc7
Since 1296cbe4b4 (init: document `init.defaultBranch` better,
2020-12-11) "git-init.adoc" has advertised that the default name
of the initial branch may change in the future. The name "main"
is chosen to match the default used by the big Git forge web sites.
The advice printed when init.defaultBranch is not set is updated
to say that the default will change to "main" in Git 3.0. Building
with WITH_BREAKING_CHANGES enabled removes the advice and changes
the default branch name to "main". The code in guess_remote_head()
that looks for "refs/heads/master" is left unchanged as that is only
called when the remote server does not support the symref capability
in the v0 protocol or the symref extension to the ls-refs list in the
v2 protocol. Such an old server is more likely to be using "master"
as the default branch name.
With the exception of the "git-init.adoc" the documentation is left
unchanged. I had hoped to parameterize the name of the default branch
by using an asciidoc attribute. Unfortunately attribute expansion
is inhibited by backticks and we use backticks to mark up ref names
so that idea does not work. As the changes to git-init.adoc show
inserting ifdef's around each instance of the branch name "master"
is cumbersome and makes the documentation sources harder to read.
Apart from "git-init.adoc" there are some other files where "master" is
used as the name of the initial branch rather than as an example of a
branch name such as "user-manual.adoc" and "gitcore-tutorial.adoc". The
name appears a lot in those so updating it with ifdef's is not really
practical. We can update that document in the 3.0 release cycle. The
other documentation where master is used as an example branch name
can be gradually converted over time.
Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
196 lines
6.1 KiB
Plaintext
196 lines
6.1 KiB
Plaintext
git-init(1)
|
|
===========
|
|
|
|
NAME
|
|
----
|
|
git-init - Create an empty Git repository or reinitialize an existing one
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[synopsis]
|
|
git init [-q | --quiet] [--bare] [--template=<template-directory>]
|
|
[--separate-git-dir <git-dir>] [--object-format=<format>]
|
|
[--ref-format=<format>]
|
|
[-b <branch-name> | --initial-branch=<branch-name>]
|
|
[--shared[=<permissions>]] [<directory>]
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
This command creates an empty Git repository - basically a `.git`
|
|
directory with subdirectories for `objects`, `refs/heads`,
|
|
`refs/tags`, and template files. An initial branch without any
|
|
commits will be created (see the `--initial-branch` option below
|
|
for its name).
|
|
|
|
If the `GIT_DIR` environment variable is set then it specifies a path
|
|
to use instead of `./.git` for the base of the repository.
|
|
|
|
If the object storage directory is specified via the
|
|
`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
|
|
are created underneath; otherwise, the default `$GIT_DIR/objects`
|
|
directory is used.
|
|
|
|
Running `git init` in an existing repository is safe. It will not
|
|
overwrite things that are already there. The primary reason for
|
|
rerunning `git init` is to pick up newly added templates (or to move
|
|
the repository to another place if `--separate-git-dir` is given).
|
|
|
|
OPTIONS
|
|
-------
|
|
|
|
`-q`::
|
|
`--quiet`::
|
|
|
|
Only print error and warning messages; all other output will be suppressed.
|
|
|
|
`--bare`::
|
|
|
|
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
|
|
current working directory.
|
|
|
|
`--object-format=<format>`::
|
|
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
|
|
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
|
|
+
|
|
include::object-format-disclaimer.adoc[]
|
|
|
|
`--ref-format=<format>`::
|
|
Specify the given ref storage _<format>_ for the repository. The valid values are:
|
|
+
|
|
include::ref-storage-format.adoc[]
|
|
|
|
`--template=<template-directory>`::
|
|
Specify the directory from which templates will be used. (See the "TEMPLATE
|
|
DIRECTORY" section below.)
|
|
|
|
`--separate-git-dir=<git-dir>`::
|
|
Instead of initializing the repository as a directory to either `$GIT_DIR` or
|
|
`./.git/`, create a text file there containing the path to the actual
|
|
repository. This file acts as a filesystem-agnostic Git symbolic link to the
|
|
repository.
|
|
+
|
|
If this is a reinitialization, the repository will be moved to the specified path.
|
|
|
|
`-b <branch-name>`::
|
|
`--initial-branch=<branch-name>`::
|
|
Use _<branch-name>_ for the initial branch in the newly created
|
|
repository. If not specified, fall back to the default name
|
|
ifndef::with-breaking-changes[]
|
|
(currently `master`, but this will change to `main` when Git 3.0 is released).
|
|
endif::with-breaking-changes[]
|
|
ifdef::with-breaking-changes[]
|
|
`main`.
|
|
endif::with-breaking-changes[]
|
|
The default name can be customized via the `init.defaultBranch` configuration
|
|
variable.
|
|
|
|
`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
|
|
|
|
Specify that the Git repository is to be shared amongst several users. This
|
|
allows users belonging to the same group to push into that
|
|
repository. When specified, the config variable `core.sharedRepository` is
|
|
set so that files and directories under `$GIT_DIR` are created with the
|
|
requested permissions. When not specified, Git will use permissions reported
|
|
by `umask`(2).
|
|
+
|
|
The option can have the following values, defaulting to `group` if no value
|
|
is given:
|
|
+
|
|
--
|
|
`umask`::
|
|
`false`::
|
|
|
|
Use permissions reported by `umask`(2). The default, when `--shared` is not
|
|
specified.
|
|
|
|
`group`::
|
|
`true`::
|
|
|
|
Make the repository group-writable, (and `g+sx`, since the git group may not be
|
|
the primary group of all users). This is used to loosen the permissions of an
|
|
otherwise safe `umask`(2) value. Note that the umask still applies to the other
|
|
permission bits (e.g. if umask is `0022`, using `group` will not remove read
|
|
privileges from other (non-group) users). See `0xxx` for how to exactly specify
|
|
the repository permissions.
|
|
|
|
`all`::
|
|
`world`::
|
|
`everybody`::
|
|
|
|
Same as `group`, but make the repository readable by all users.
|
|
|
|
_<perm>_::
|
|
|
|
_<perm>_ is a 3-digit octal number prefixed with `0` and each file
|
|
will have mode _<perm>_. _<perm>_ will override users' `umask`(2)
|
|
value (and not only loosen permissions as `group` and `all`
|
|
do). `0640` will create a repository which is group-readable, but
|
|
not group-writable or accessible to others. `0660` will create a repo
|
|
that is readable and writable to the current user and group, but
|
|
inaccessible to others (directories and executable files get their
|
|
`x` bit from the `r` bit for corresponding classes of users).
|
|
--
|
|
|
|
By default, the configuration flag `receive.denyNonFastForwards` is enabled
|
|
in shared repositories, so that you cannot force a non fast-forwarding push
|
|
into it.
|
|
|
|
If you provide a _<directory>_, the command is run inside it. If this directory
|
|
does not exist, it will be created.
|
|
|
|
TEMPLATE DIRECTORY
|
|
------------------
|
|
|
|
Files and directories in the template directory whose name do not start with a
|
|
dot will be copied to the `$GIT_DIR` after it is created.
|
|
|
|
The template directory will be one of the following (in order):
|
|
|
|
- the argument given with the `--template` option;
|
|
|
|
- the contents of the `$GIT_TEMPLATE_DIR` environment variable;
|
|
|
|
- the `init.templateDir` configuration variable; or
|
|
|
|
- the default template directory: `/usr/share/git-core/templates`.
|
|
|
|
The default template directory includes some directory structure, suggested
|
|
"exclude patterns" (see linkgit:gitignore[5]), and sample hook files.
|
|
|
|
The sample hooks are all disabled by default. To enable one of the
|
|
sample hooks rename it by removing its `.sample` suffix.
|
|
|
|
See linkgit:githooks[5] for more general info on hook execution.
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
Start a new Git repository for an existing code base::
|
|
+
|
|
----------------
|
|
$ cd /path/to/my/codebase
|
|
$ git init <1>
|
|
$ git add . <2>
|
|
$ git commit <3>
|
|
----------------
|
|
+
|
|
<1> Create a `/path/to/my/codebase/.git` directory.
|
|
<2> Add all existing files to the index.
|
|
<3> Record the pristine state as the first commit in the history.
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
|
|
include::includes/cmd-config-section-all.adoc[]
|
|
|
|
:git-init:
|
|
|
|
include::config/init.adoc[]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|