Git documentation is NOT well-written and clear

1

Git is really not that difficult. I am the first to admit that. There a just strings of characters forming commands after all, right? Everything should work just fine unless somehow you do not have it configured correctly. Well that is the problem!

Several times I have been referred back to the Git documentation by well-meaning techies claiming that it is “helpful”,“well-written” and “clear”. Well I have to say that it is simply is not any of those things or there would not be so many people having problems.

In my opinion everything in the Git Documentation is reasonably clear up until 1.6 Getting Started - First-Time Git Setup, which by the way is critical. From this point on, my comments will be in italics, the rest is copied and pasted directly from the the above-mentioned section.

First-Time Git Setup

Now that you have Git on your system, you’ll want to do a few things to customize your Git environment. You should have to do these things only once on any given computer; they’ll stick around between upgrades. You can also change them at any time by running through the commands again.

this implies that I should do something first, ie customize my Git environment. So far so good

Git comes with a tool called git config that lets you get and set configuration variables that control all aspects of how Git looks and operates. These variables can be stored in three different places:

  1. /etc/gitconfig file: Contains values applied to every user on the system and all their repositories. If you pass the option --system to git config, it reads and writes from this file specifically. (Because this is a system configuration file, you would need administrative or superuser privilege to make changes to it.)
  2. ~/.gitconfig or ~/.config/git/config file: Values specific personally to you, the user. You can make Git read and write to this file specifically by passing the --global option, and this affects all of the repositories you work with on your system.
  3. config file in the Git directory (that is, .git/config) of whatever repository you’re currently using: Specific to that single repository. You can force Git to read from and write to this file with the --local option, but that is in fact the default. (Unsurprisingly, you need to be located somewhere in a Git repository for this option to work properly.)

So using the tool git config is the how you set configuration variables and they are stored in the three above mentioned files. ok, intersting.

Each level overrides values in the previous level, so values in .git/config trump those in /etc/gitconfig.

ok got it

On Windows systems, Git looks for the .gitconfig file in the $HOME directory (C:\Users$USER for most people). It also still looks for /etc/gitconfig, although it’s relative to the MSys root, which is wherever you decide to install Git on your Windows system when you run the installer. If you are using version 2.x or later of Git for Windows, there is also a system-level config file at C:\Documents and Settings\All Users\Application Data\Git\config on Windows XP, and in C:\ProgramData\Git\config on Windows Vista and newer. This config file can only be changed by git config -f <file> as an admin.

for most people? i do not really care what most people do. I am reading this documentation at this point to do a first time set-up. And seeing from the previous page that in order to use git on windows I was going to need to install a ton of stuff to my computer, then STILL possibly have problems, I decided to use the github desktop app. So now what?

Your Identity

The first thing you should do when you install Git is to set your user name and email address. This is important because every Git commit uses this information, and it’s immutably baked into the commits you start creating:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Again, you need to do this only once if you pass the --global option, because then Git will always use that information for anything you do on that system. If you want to override this with a different name or email address for specific projects, you can run the command without the --global option when you’re in that project.

Many of the GUI tools will help you do this when you first run them.

So now that I am already confused with what you implied was the first step, customize my Git environment, they tell me that the first step is this easy-peasy command to set my user name and email. So which one is it?

I will not even bother with the rest of the page, since it matters so little with the very first steps being so unclear.

Please someone help to make sense of this. Thank you.

2

If you are using the Desktop app I would recommend following the guide specific to that:

If you’d like to use the terminal version of git (which is very useful to learn, and not that difficult once you have a handle on a typical workflow), then stick with the terminal guide and don’t worry about the possibility of something going wrong - cross that bridge if and when you come to it. I guarantee any issues you face setting up git have been overcome by many, many people before you, and the solutions will be a simple Google search away.

Just take your time, read the docs carefully, copy-and-paste commands to avoid typos, and post more specific questions here if you get really stuck.

If you do want to try the terminal version, you might find installing and using git-bash to be helpful. I think it even comes with git, iirc. It’s a terminal designed for git on Windows and it overcomes some of the quirks you might find trying to run git via cmd or PowerShell.

3

My apologies - I see from a previous post that you’ve tried git-bash already, I think.

4

I saw in another thread that I can’t seem to find now that you had some questions about the terminology surrounding passing options to commands in the command line?

(If the forum were behaving a little better I’d merge the threads, but the servers are going bananas at the moment)

Anyway, I think you had an issue with this line in a setup doc you found:

  • /etc/gitconfig file: Contains values for every user on the system and all their repositories. If you pass the option --system to git config , it reads and writes from this file specifically.

This is explaining how to use basic terminal commands and then add other options to them.

I agree it is not clear if you have never touched the terminal before.

The suggestion there is to write this in the terminal:

git config --system

Terminal programs generally follow the pattern of:

name command --options

5

Would you be willing to just answer the questions I have posed above? What is the first step , configuration or setting name and email? Why does everyone just suggest other tutorials? I can find them myself. I think what I am asking is for clarification of what is supposed to be the technical documentation for first time git users. It should be clarified.

Yes, I was using git bash but after not having initialized it correctly I decided to uninstall and start over

1 Like
6

Configuring your git is setting the name and email.

There are other things you can configure as well, but don’t bother. Just use the defaults until you know what the difference is. (e.g. you don’t really care if your git editor is vim or emacs, yet)

So:

  1. install git
  2. open git bash
  3. type:
git config --global user.name "Elaine Surname"
git config --global user.email elaine@example.com
  1. and then you are ready to start using git.

If you want to use the terminal, it is helpful to find a short terminal tutorial.

You’ll basically only really need the cd command to get started. You use cd to change directories.

So, let’s say you are in a folder called home and you have a project in demo (which is in home.)

From home you can type cd demo and it’ll move you to that folder.

In there type git init and that will initialise git for that project. Then you are ready to use git on that project.

2 Likes
7

As JacksonBates said, configuration is setting the name and email.

If you are using the GUI then you may not need to do this step. However if you don’t have experience using the terminal, it’s worth it to learn. Not everything has GUI you can fall back on. This is a really good tutorial you can follow along with:

https://learnpythonthehardway.org/book/appendixa.html

The Git documentation is clear, with background…you’ll find that many tutorials will expect you to have background in other things.

8

Ah yay! Thank you very much!

9

Thank you. Yes I am interested in learning the terminal. I will check that tutorial out later.

10

Sorry if I was being grouchy in my last response. This is really clear now. Thank very much for breaking it down. I really appreciate it.

11

No problem, I understand how frustrating it is to get stuck for days on seemingly trivial things that should just work :slight_smile:

So does this mean you have git running properly on your computer now?

12

[quote=“JacksonBates, post:6, topic:233121”]

Yes very frustrating but I am determined. I initialized the new git download and there it is, appearing to be fine. Next I was going to make a directory and trying to decide where to put it so opened Visual Studio Code to see where I have my project.

I still get the message
The git repository at ‘c:\Users\adminname’ has too many active changes, only a subset of Git features will be enabled

I still do not want to give up though.

13

Hmm, I think you may have run git init on all of your documents, not just one project.

Each time you start a new project in its own folder, run git init there to use git for that project.

14

Hello Jackson. Taking a break seems to have been a good choice because it seems like I have fixed the problems that I was having. Now I would like to test doing a push to git from visual studio code. The 5000+ untracked changes have vanished but now I only have my vscode\settings.json file showing as an untracked change. I added it to .gitignore and then my .gitignore file was listed as an untracked change. This might seem very obvious but I have two questions 1. should I do something in my settings to prevent this file from being created in the first place and 2. what should I be doing generally speaking with untracked files that appear, including the untracked .gitignore if I choose to ignore them?

I hope the question makes sense.

15

I’m not sure if this is just a Rails thing, but some .gitignore file templates have something like this at the top:

# See https://help.github.com/articles/ignoring-files for more about ignoring files.
#
# If you find yourself ignoring temporary files generated by your text editor
# or operating system, you probably want to add a global ignore instead:
#   git config --global core.excludesfile '~/.gitignore_global'

That last line gives you another config command for ignoring stuff like the .vscode/settings.json file.

You do want the file to be created, since sometimes you have specific settings for your editor that may change between projects.

For what it’s worth, at work we actually commit the .vscode/settings.json file to the repo for everyone to share, since it helps us keep our Prettier plugin settings the same for everyone.

16

Thank you again. In this case I am trying to work with a fellow student on a project so i think I will commit the settings. Based on what you say and what I have read this seems to be fairly common when collaborating with others. But I will keep that command in mind in case find more editor generated files in the future.

1 Like