Why Git?

• git tracks changes. (The git program and the github website are properly all lower case. I am sometimes improper.) 

  •  git calls a set of changes a commit.

  • A commit is like a snapshot of the set of files being tracked. Each commit has:

    1. 1. What was changed (files & line numbers) from the previous commit

       2. A unique ID (the first 7 characters are used to identify it)

       3. When the commit was made

       4. Who made the commit

       5. A one line description/title for the commit

       6. Optionally additional lines/paragraphs describing the commit

• git allows reverting with multiple files

• Git Blame tells you which commit is responsible for an individual line or group of lines.

• Git only tracks differences with text files. Office Document files (*.doc, *.docx), spreadsheets (*.xls, *.xlsx)

• Microsoft PowerPoint files (*.ppt, *.pptx)

• PDF files (*.pdf)

• 
  

• Git allows "send/receive" to a  remote  git server  like github. I have used github as a blanket term for the server. Other servers include Gitlab, Bitbucket and Codeberg.

Essential Git Commands/Processes

Here is a list of commands that are available git bash, the git command line. Most of them are available with menu items and buttons in the git gui.  (Another graphical interface that some find more intuitive for accessing github is GitHub Desktop)

• git clone -> bring a repo down from the internet, e.g. github, to your local machine

• git add -> stage your files and changes with Git; with the git gui you can add lines/chunks.

• git commit -> save your changes into the git repo

• git push -> push your changes to your remote repo on github

• git pull -> pull changes down from the remote repo to your local machine. Same as fetch & merge. If you're the only one using the repo just use pull.

• git status -> check to see which files are being tracked or need to be committed. The git gui provides this information graphically.

• git init -> use this command inside of your directory to turn it into an empty Git repository.

• git log -> see recent commits or use the gitk gui to see the history.

• git blame -> See which commits apply to a given line/section of a file, part of the git gui file viewer.

What to include in the git repo

• SFM file(s)

• List of SFM markers

  • You will probably want to save your list as a spreadsheet

  • If you want to track the changes in the list/descriptions, save it as a CSV file

• You may want to include a Solid file.

• It may be useful to archive the Toolbox Control files in your Git repo.

• Running notes

  • Commit messages allow you to give brief summaries of what a group of changes accomplishes.

  • For some parts of the import process, you will want to document multiple steps. For this, you may want a separate file that contains your notes.

Working in git

Working directory

• Use the .gitignore file to keep files / sub-directories from being included
  Here's a sample that ignores some common backup files and the Temp sub-directory:

#ignore backup files

*.idx

*.bak

*~

Temp/

Staging area

This is not a specific area, but is an indication of which files and changes will be included in the commit. You can add files or changes to a commit easily in the git gui.

Commit Message

The standard for the format for a commit message is:

<first line>
<blank line>
<bulleted comments about the commit>

The commit message first line is special and acts as title to the commit. It should answer briefly the question "Why are you making the changes?"

The bulleted comments start with a space and an asterisk.  They can include find/replace strings or any code that you used to make the changes. It should answer the question "How did you make the changes"

If your change includes a specially written script, you should briefly document that script in the bulleted comments.

An Example Commit Message

Here's an example of a fairly complicated commit for a Quechua project.
Most of the \so fields were under senses, but they should go into an entry level FLEx field. Here is the commit message for the change that moved the \so fields to the entry level:

    Move \so to the entry level

    * Entry level is before the first \ge, \sn or \ps
    * Did it with:
      perl -pf ../opl.pl Quechua.db |\
      perl -pE 's/(\\(ge|sn|ps) .*?)(\\so [^#]*#)/$3$1/' |\
      perl -pf ../de_opl.pl >Quechua1.db

    * verify and mv Quechua1.db Quechua.db