Git - Quick Start

Using Git for collaborating on text-based data files

The instruction here is based on command-line interface (cmd/PowerShell on Windows, Terminal on OS X or Linux, or ssh clients). If you are using a GUI, the commands should closely match the command line-based commands and parameters, and the workflow does not change.

Setting up the environment

Install Git on the same machine that you have the project files. Usually, you can install git from https://git-scm.com/. If you're on OS X, you can also use Homebrew to install it. On Linux machines, Git is available via the built-in package manager on most of distributions.

Unless you are starting from scratch, you need to download an existing project files that people are collaborating on. Cloning in Git copies from the source repository and makes a copy on your local machine. For example, if our project repository URL is https://github.com/myaccount/rime-zhengma, then you would execute the following to create the project folder:

$ git clone https://github.com/myaccount/rime-zhengma

A folder called rime-zhengma should have been created. You now have a local copy of the project. Whatever changes you make on this local copy will not affect the remote repository until you make a pull request. The copy on myaccount repository can be freely updated since it's your copy on GitHub. As of now, you can change into the folder and do your edits.

Saving or committing your edits or additions

Once you are done editing or adding new files to the project, you can check the current state of your working tree with the following command.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   helpers.php
        modified:   package.json
        modified:   webpack.mix.js

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        CasGuard.php
        Controller.php
        app-extra.php
        common.php
        resources/views/layouts/
        web.php

no changes added to commit (use "git add" and/or "git commit -a")

(The names of files in your environment may look different.) In git there are four states to any file under your project folder. They are untracked, unmodified, modified, staged, and committed. Committed files do not appear in git status unless you execute the command to view them. Those files listed under "Changes not staged for commit" are the files you've changed, and "Untracked files" are the new files you've created that aren't not part of the project yet. The modified files can be moved to the staging area for commit.

Now, change in to your project root. In the example above, we had created the project folder called rime-zhengma. If it was created under /Users/mhan folder, then the project root location would be /Users/mhan/rime-zhengma folder. Once on project root, type the following:

$ git add .
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        new file:   CasGuard.php
        new file:   Controller.php
        new file:   app-extra.php
        new file:   common.php
        modified:   helpers.php
        modified:   package.json
        new file:   resources/views/layouts/base.blade.php
        new file:   web.php
        modified:   webpack.mix.js

Above command will add both changed and untracked files into the staging area for commit. Think of a short description text that starts with a verb in present tense.

$ git commit -m 'add CAS custom authentication controlller'
[main e4d0581] add CAS custom authentication controlller
 9 files changed, 617 insertions(+), 1 deletion(-)
 create mode 100644 CasGuard.php
 create mode 100644 Controller.php
 create mode 100644 app-extra.php
 create mode 100644 common.php
 create mode 100644 resources/views/layouts/base.blade.php
 create mode 100644 web.php

Now you've committed your changes to your local repository. Now, you're ready to make a pull request if you want your change to be a part of the remote repository.

For more in-depth documentation on Git, you can access a free online book, Pro Git.

For learning Git via online, checkout Resources to learn Git.