Introduce Git in two parts:
Steps 1-7: Create an empty repo & make 2 commits (`git init`,
`git add`, `git commit`, `git status`, `git diff`)
Steps 8-12: Push the repo to a remote host like GitHub or GitLab
(`git remote add`, `git push`)
Some design choices:
- Only use commands present in 2.23.0 (when `git switch` as introduced),
to support older versions of Git.
- Introduce a much smaller set of commands than the old tutorial, to
keep the tutorial quick (doable in an hour). Some users found it to be
very fast and some wanted to stop early (after step 7) so this seems
to be a good balance.
- Have users start with an empty repository instead of an existing
project, because many of the testers did not have an existing project
to test, or were scared of using an existing project.
- Add a troubleshooting section, since in the testing some users got
extremely stuck (for 4+ hours) on minor issues like needing to say
"yes" when SSHing to a new host.
- Don't explain branches, because explaining branches and collaboration
is complicated and deserves its own tutorial. Instead just tell users
we're not going to explain them in this document.
- Tell users to set their default branch to `main`, because many Git
hosts use it as their default branch and it really simplifies things.
- Keep it as vendor neutral as possible, while acknowledging the reality
that Git hosting services like GitHub, GitLab, etc are extremely
popular. Do this by creating the repo locally and then optionally
pushing it later.
- Use SSH for authentication, explaining how to set up SSH in the
easiest way possible (with disclaimers to check your security team's
policy if applicable since the "easiest way" may not be the best), and
giving some instructions for how to translate an HTTPS URL to an SSH
URL.
- Use Git Credential Manager for authentication on Windows, since it's
simpler, SSH auth is a very "unixy" thing to do, and GCM comes with
Git for Windows
- Warn people about how `vi` is the default text editor and give some
instructions for how to escape
At least 20 people have successfully completed it, and feedback was
incorporated from problems the testers ran into.
Helped-by: D. Ben Knoble <ben.knoble@gmail.com>
Co-authored-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The next commit replaces it with a new tutorial.
Do this as a remove/add instead of just replacing the file in a single
commit to make the patches easier to read on the mailing list, since the
existing content isn't being reused.
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Replace uses of `git config --list` (short or long) with the subcommand
`list` since `--list` is deprecated.
We will change the “man page” phrasing in gitcvs-migration(7) in the
next commit, since we are already visiting that sentence. But note
that we leave the “man page” phrasing in the sentence that we touch in
gittutorial(7) since it’s a tutorial and not a manual page. We can be
more wordy in a tutorial context.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We presently use the ".txt" extension for our AsciiDoc files. While not
wrong, most editors do not associate this extension with AsciiDoc,
meaning that contributors don't get automatic editor functionality that
could be useful, such as syntax highlighting and prose linting.
It is much more common to use the ".adoc" extension for AsciiDoc files,
since this helps editors automatically detect files and also allows
various forges to provide rich (HTML-like) rendering. Let's do that
here, renaming all of the files and updating the includes where
relevant. Adjust the various build scripts and makefiles to use the new
extension as well.
Note that this should not result in any user-visible changes to the
documentation.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
