git/Documentation/git-init.txt, branch v2.41.2

docs: add CONFIGURATION sections that fuzzy map to built-ins

2022-09-07T16:46:07Z

Add a CONFIGURATION section to the documentation of various built-ins, for those cases where the relevant config/NAME.txt doesn't map only to one git-NAME.txt. In particular: * config/blame.txt: used by git-{blame,annotate}.txt. Since the git-annotate(1) documentation refers to git-blame(1) don't add a "CONFIGURATION" section to git-annotate(1), only to git-blame(1). * config/checkout.txt: maps to both git-checkout.txt and git-switch.txt (but nothing else). * config/init.txt: should be included in git-init(1) and git-clone(1). * config/column.txt: We should ideally mention the relevant subset of this in git-{branch,clean,status,tag}.txt, but let's punt on it for now. We will when we eventually split these sort of files into e.g. config/column.txt and config/column/{branch,clean,status,tag}.txt, with the former including the latter set. Things that are being left out, and why: * config/{remote,remotes,credential}.txt: Configuration that affects how we talk to remote repositories is harder to untangle. We'll need to include some of this in git-{fetch,remote,push,ls-remote}.txt etc., but some of those only use a small subset of these options. Let's leave this for now. Signed-off-by: Ævar Arnfjörð Bjarmason Reviewed-by: Matheus Tavares Signed-off-by: Junio C Hamano

init doc: --shared=0xxx does not give umask but perm bits

2021-11-09T17:39:11Z

The description that 0640 makes sure that the group members can read the repository is correct, but calling that octal number a is wrong. Let's call it , as the value is used to set the permission bits. Signed-off-by: Junio C Hamano

doc: git-init: clarify file modes in octal.

2021-11-09T17:39:11Z

The previous explanation was mixing the format with the identity of the field. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

doc: use only hyphens as word separators in placeholders

2021-11-09T17:39:11Z

According to CodingGuidelines, multi-word placeholders should use hyphens as word separators. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano Reviewed-by: Eli Schwartz Signed-off-by: Junio C Hamano

doc: express grammar placeholders between angle brackets

2021-11-09T17:39:11Z

This discerns user inputs from verbatim options in the synopsis. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

init: document `init.defaultBranch` better

2020-12-13T23:53:50Z

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 Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano

doc: fix the bnf like style of some commands

2020-10-08T21:01:19Z

In command line options, variables are entered between < and > Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

Documentation: mark `--object-format=sha256` as experimental

2020-08-17T17:50:14Z

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 Signed-off-by: Junio C Hamano

init: allow specifying the initial branch name for the new repository

2020-06-24T16:14:21Z

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=`. Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano

docs: add missing diamond brackets

2020-06-24T16:14:21Z

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 Signed-off-by: Junio C Hamano