summaryrefslogtreecommitdiff
path: root/Documentation/git-init.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-12-13init: document `init.defaultBranch` betterLibravatar Johannes Schindelin1-4/+7
Our documentation does not mention any future plan to change 'master' to other value. It is a good idea to document this, though. Initial-patch-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-08doc: fix the bnf like style of some commandsLibravatar Jean-Noël Avila1-1/+1
In command line options, variables are entered between < and > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-08-17Documentation: mark `--object-format=sha256` as experimentalLibravatar Martin Ågren1-0/+2
After eff45daab8 ("repository: enable SHA-256 support by default", 2020-07-29), vanilla builds of Git enable the user to run, e.g., git init --object-format=sha256 and hack away. This can be a good way to gain experience with the SHA-256 world, e.g., to find bugs that GIT_TEST_DEFAULT_HASH=sha256 make test doesn't spot. But it really is a separate world: Such SHA-256 repos will live entirely separate from the (by now fairly large) set of SHA-1 repos. Interacting across the border is possible in principle, e.g., through "diff + apply" (or "format-patch + am"), but even that has its limitations: Applying a SHA-256 diff in a SHA-1 repo works in the simple case, but if you need to resort to `-3`, you're out of luck. Similarly, "push + pull" should work, but you really will be operating mostly offset from the rest of the world. That might be ok by the time you initialize your repository, and it might be ok for several months after that, but there might come a day when you're starting to regret your use of `git init --object-format=sha256` and have dug yourself into a fairly deep hole. There are currently topics in flight to document our data formats and protocols regarding SHA-256 and in some cases (midx and commit-graph), we're considering adjusting how the file formats indicate which object format to use. Wherever `--object-format` is mentioned in our documentation, let's make it clear that using it with "sha256" is experimental. If we later need to explain why we can't handle data we generated back in 2020, we can always point to this paragraph we're adding here. By "include::"-ing a small blurb, we should be able to be consistent throughout the documentation and can eventually gradually tone down the severity of this text. One day, we might even use it to start phasing out `--object-format=sha1`, but let's not get ahead of ourselves... There's also `extensions.objectFormat`, but it's only mentioned three times. Twice where we're adding this new disclaimer and in the third spot we already have a "do not edit" warning. From there, interested readers should eventually find this new one that we're adding here. Because `GIT_DEFAULT_HASH` provides another entry point to this functionality, document the experimental nature of it too. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-06-24init: allow specifying the initial branch name for the new repositoryLibravatar Johannes Schindelin1-0/+7
There is a growing number of projects and companies desiring to change the main branch name of their repositories (see e.g. https://twitter.com/mislav/status/1270388510684598272 for background on this). To change that branch name for new repositories, currently the only way to do that automatically is by copying all of Git's template directory, then hard-coding the desired default branch name into the `.git/HEAD` file, and then configuring `init.templateDir` to point to those copied template files. To make this process much less cumbersome, let's introduce a new option: `--initial-branch=<branch-name>`. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-06-24docs: add missing diamond bracketsLibravatar Johannes Schindelin1-1/+1
There were a couple of instances in our manual pages that had an opening diamond bracket without a corresponding closing one. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-24builtin/init-db: allow specifying hash algorithm on command lineLibravatar brian m. carlson1-1/+6
Allow the user to specify the hash algorithm on the command line by using the --object-format option to git init. Validate that the user is not attempting to reinitialize a repository with a different hash algorithm. Ensure that if we are writing a non-SHA-1 repository that we set the repository version to 1 and write the objectFormat extension. Restrict this option to work only when ENABLE_SHA256 is set until the codebase is in a situation to fully support this. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-06Merge branch 'km/init-doc-typofix'Libravatar Junio C Hamano1-1/+1
Docfix. * km/init-doc-typofix: init docs: correct a punctuation typo
2019-01-31init docs: correct a punctuation typoLibravatar Kyle Meyer1-1/+1
Signed-off-by: Kyle Meyer <kyle@kyleam.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-26Documentation: do not nest open blocksLibravatar Martin Ågren1-4/+0
It appears we try to nest open blocks, but that does not work well with Asciidoctor, which fails to indent the inner blocks. As a result, they do not visually seem to relate (as much) to the preceding paragraph as they should. Drop the outer blocks to fix the rendering of the inner ones. Asciidoc renders identically before and after this patch, both man-pages and html. This also makes Asciidoctor stop rendering a literal '+' before "Under --pretty=oneline ..." in the manuals for git-log and git-rev-list. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-02-17init: document dotfiles exclusion on template copyLibravatar Grégoire Paris1-2/+2
Not just . and .., but any path that begins with dot is not copied when copying the template directory to a new repository. You can customize the template directory, copying some dotfiles might make sense, but it's actually a good thing not to, because you would not want to have your git directory copied in every git directory that is created should you decide to put your template directory under version control, for example. Plus, it might be used as a feature by people who would want to exclude some files. Signed-off-by: Grégoire Paris <postmaster@greg0ire.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-27Merge branch 'tr/doc-tt'Libravatar Junio C Hamano1-1/+1
The documentation set has been updated so that literal commands, configuration variables and environment variables are consistently typeset in fixed-width font and bold in manpages. * tr/doc-tt: doc: change configuration variables format doc: more consistency in environment variables format doc: change environment variables format doc: clearer rule about formatting literals
2016-06-08doc: more consistency in environment variables formatLibravatar Tom Russello1-1/+1
Wrap with backticks (monospaced font) unwrapped or single-quotes wrapped (italic type) environment variables which are followed by the word "environment". It was obtained with: perl -pi -e "s/\'?(\\\$?[0-9A-Z\_]+)\'?(?= environment ?)/\`\1\`/g" *.txt One of the main purposes is to stick to the CodingGuidelines as possible so that people writting new documentation by mimicking the existing are more likely to have it right (even if they didn't read the CodingGuidelines). Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org> Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-04githooks.txt: improve the intro sectionLibravatar Ævar Arnfjörð Bjarmason1-1/+6
Change the documentation so that: * We don't talk about "little scripts". Hooks can be as big as you want, and don't have to be scripts, just call them "programs". * We note that we change the working directory before a hook is called, nothing documented this explicitly, but the current behavior is predictable. It helps a lot to know what directory these hooks will be executed from. * We don't make claims about the example hooks which may not be true depending on the configuration of 'init.templateDir'. Clarify that we're talking about the default settings of git-init in those cases, and move some of this documentation into git-init's documentation about the default templates. * We briefly note in the intro that hooks can get their arguments in various different ways, and that how exactly is described below for each hook. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-1/+1
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: flesh out exampleLibravatar Linus Arver1-0/+2
Add a third step `git commit` after adding files for the first time. Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: template directory: reword and cross-referenceLibravatar Linus Arver1-3/+2
Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: reword parenthetical statementsLibravatar Linus Arver1-2/+2
Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: --separate-git-dir: clarifyLibravatar Linus Arver1-6/+6
Use shorter sentences to describe what actually happens. We describe what the term "Git symbolic link" actually means. Also, we separate out the description of the behavioral change upon reinitialization into its own paragraph. Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: template directory: rewordLibravatar Linus Arver1-5/+5
Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: list items faceliftLibravatar Linus Arver1-21/+28
No textual change. Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-08-08Documentation: git-init: typographical fixesLibravatar Linus Arver1-6/+5
Use backticks when we quote something that the user should literally use. Signed-off-by: Linus Arver <linusarver@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-8/+8
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-07-06Documentation: use [verse] for SYNOPSIS sectionsLibravatar Martin von Zweigbergk1-0/+1
The SYNOPSIS sections of most commands that span several lines already use [verse] to retain line breaks. Most commands that don't span several lines seem not to use [verse]. In the HTML output, [verse] does not only preserve line breaks, but also makes the section indented, which causes a slight inconsistency between commands that use [verse] and those that don't. Use [verse] in all SYNOPSIS sections for consistency. Also remove the blank lines from git-fetch.txt and git-rebase.txt to align with the other man pages. In the case of git-rebase.txt, which already uses [verse], the blank line makes the [verse] not apply to the last line, so removing the blank line also makes the formatting within the document more consistent. While at it, add single quotes to 'git cvsimport' for consistency with other commands. Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-25init/clone: remove short option -L and document --separate-git-dirLibravatar Nguyen Thai Ngoc Duy1-2/+1
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-19init, clone: support --separate-git-dir for .git fileLibravatar Nguyễn Thái Ngọc Duy1-2/+15
--separate-git-dir tells git to create git dir at the specified location, instead of where it is supposed to be. A .git file that points to that location will be put in place so that it appears normal to repo discovery process. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-19git-init.txt: move description section upLibravatar Nguyễn Thái Ngọc Duy1-26/+20
It's more or less standard that synopsis is followed by description, then options. This is not just a clean move though: - The paragraphs are realigned a bit - The text mentioning git-init-db is dropped. init-db is deprecated, no need to confuse new users Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-9/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-10-08Use parentheses and `...' where appropriateLibravatar Štěpán Němec1-1/+1
Remove some stray usage of other bracket types and asterisks for the same purpose. Signed-off-by: Štěpán Němec <stepnem@gmail.com> Acked-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-17Add a "TEMPLATE DIRECTORY" section to git-init[1].Libravatar Steven Drake1-8/+21
Create a more inoformative section to describe template directory and refer to it in config.txt and with the '--template' option of git-init and git-clone commands. Signed-off-by: Steven Drake <sdrake@xnet.co.nz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-10Documentation: spell 'git cmd' without dash throughoutLibravatar Thomas Rast1-3/+3
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-07-25git init: optionally allow a directory argumentLibravatar Nanako Shiraishi1-1/+4
When starting a new repository, I see my students often say % git init newrepo and curse git. They could say % mkdir newrepo; cd newrepo; git init but allowing it as an obvious short-cut may be nicer. Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-18Update docs on behaviour of 'core.sharedRepository' and 'git init --shared'Libravatar Johan Herland1-5/+11
This documentation update is needed to reflect the recent changes where "core.sharedRepository = 0mode" was changed to set, not loosen, the repository permissions. Signed-off-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: italicize git command names (which were in teletype font)Libravatar Jonathan Nieder1-3/+3
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-3/+3
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-08Docs: Use "-l::\n--long\n" format in OPTIONS sectionsLibravatar Stephan Beyer1-1/+2
The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer <s-beyer@gmx.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-28git-init: accept --bare optionLibravatar Luciano Rocha1-1/+6
It is unfortunate that "git init --bare" does not work and the only reason why "init" did not learn its own "--bare" option is because "git --bare init" already does the job (and as an option to the git 'potty', it is more generic solution). This teaches "git init" its own "--bare" option, so that both "git --bare init" and "git init --bare" works mostly the same way. [jc: rewrote the log message and added test] Signed-off-by: Luciano Rocha <strange@nsk.pt> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-04-16Make core.sharedRepository more genericLibravatar Heikki Orsila1-1/+7
git init --shared=0xxx, where '0xxx' is an octal number, will create a repository with file modes set to '0xxx'. Users with a safe umask value (0077) can use this option to force file modes. For example, '0640' is a group-readable but not group-writable regardless of user's umask value. Values compatible with old Git versions are written as they were before, for compatibility reasons. That is, "1" for "group" and "2" for "everybody". "git config core.sharedRepository 0xxx" is also handled. Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-1/+1
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-18Fix some documentation typos.Libravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-06-27Add an option to quiet git-init.Libravatar Jeffrey C. Ollie1-1/+5
git-init lacks an option to suppress non-error and non-warning output - this patch adds one. Signed-off-by: Jeffrey C. Ollie <jeff@ocjtech.us> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-06-07War on whitespaceLibravatar Junio C Hamano1-1/+0
This uses "git-apply --whitespace=strip" to fix whitespace errors that have crept in to our source files over time. There are a few files that need to have trailing whitespaces (most notably, test vectors). The results still passes the test, and build result in Documentation/ area is unchanged. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-01-18Documentation: sync git.txt command list and manual page titleLibravatar Junio C Hamano1-1/+1
Also reorders a handful entries to make each list sorted alphabetically. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-12use 'init' instead of 'init-db' for shipped docs and toolsLibravatar Nicolas Pitre1-3/+1
While 'init-db' still is and probably will always remain a valid git command for obvious backward compatibility reasons, it would be a good idea to move shipped tools and docs to using 'init' instead. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-11Document git-initLibravatar Junio C Hamano1-1/+113
These days, the command does a lot more than just initialise the object database (such as setting default config-variables, installing template hooks...), and "git init" is actually a more sensible name nowadays. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-10Add git-init documentation.Libravatar Nicolas Pitre1-0/+1
Oops. Commit 515377ea9ec6192f82a2fa5c5b5b7651d9d6cf6c missed one file, git-init documentation. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>