Git Local Repositories for the Impatient

2017 05 02 head

You shall put your source code and text documentation under a version management system.

The actual industrial standard for version control systems is git, a distributed version control system - DVCS -. It tracks changes in any set of computer files, usually used for coordinating work among programmers who are collaboratively developing source code during software development.

Subversion was a great tool and should now be retired. Simple refactoring activities with renaming will already corrupt a subversion repository. Commit operations can take quite some time before completing.

Install git on your development machine.

Binaries are available for all major platforms and can be found under Downloads GUI clients are also provided for all major platforms [1].

If you want higher security, you should install ssh. The operation is trivial for linux and macOS systems. It is more cumbersome on Microsoft Windows systems.

In case you are using the IntelliJ IDEA configure Git in the IDE through the preference pane.

Graphical Git clients are available. I sometimes use the free-available SourceTree.

Create a Local Repository

To put your product under git version management, go to the root of the product and perform the command

git init

You have want to have a local copy of an existing git repository:

git clone <repository link>     (1)
1 The link is either the https or an ssh link to the remote repository.

Once you have a local copy of a shared repository, you can update your copy with the changes of the remote repository using:

git pull

To add a specific file or all your source files to git.

git add [filename]
git add *

You shall perform these operations to add a product to a local Git repository directly in IntelliJ IDEA:

  1. Open the product you want to store in a repository.

  2. On the main menu, choose VCS | Import into Version Control | Create Git Repository.

  3. In the dialog that opens, specify the directory where you want to create a new Git repository.

  4. Put the required files under Git version control. The files appear in the Local Changes tab of the Version Control tool window, under the Default change list.

You can define the set of files which git should ignore in the .gitignore configuration file. See gitignore for details.

Your IDE shall support this feature and would add files or folder to ignore through its user interface.

Commit Changes

To commit your changes, you simply:

git commit -m "commit message, should be clear and legible"         (1)
1 Development platforms such as GitHub, GitLab orhttps://bitbucket.org/[Bitbucket] often support linking commit messages containing keywords with work items and tickets.

You can perform these operations directly in IntelliJ IDEA using the provided VCS functions. Switch to the Version Control tool window and switch to the Local Changes tab.

  1. Expand the Un-versioned Files node and select the files to be added. From the context menu, choose to Add to VCS, or press ⌥⌘A.

  2. Switch to the Project tool window and select the files to be added. From the context menu, choose Git | Add or press⌥⌘A.

Each time you commit your changes, you gain the ability to reverse back to exactly this state. Each time you made a modification and tested it, commit it. The cost of a commit is marginal. When working with Git, TDD, and ATDD, it is normal to commit every few minutes. By a few minutes, we mean 5 or 10 minutes.

Observe yourself. If you commit at the end of the day, you are using your DVCS as a backup medium. It is time to change your habits. Use Git as a history of all successful changes you implement and roll back all unsuccessful ones, simply discarding them.

If you forget some files when performing the last commit, you can correct it:

git commit --amend   (1)
1 Please do not amend shared commits. Amending a commit shared with another user will potentially require confusing and lengthy merge conflict resolutions.

Once you are satisfied with your changes, you can propagate them to the remote repository using:

git push

What is Your Project Status?

To find out what the status of your product is, simply

git status                                      (1)
git log                                         (2)
git diff                                        (3)
1 status of your local copy with modified files, and untracked files.
2 list of commits with detailed information.
3 shows the changes in edited files.

The same information is available in IntelliJ IDEA under

  1. Open the required product

  2. On the main menu, choose VCS | Refresh File Status

  3. Switch to the Version Control window and open the Local Changes tab.

Always Work with Trunk

Ideally, you shall always work against the trunk, also called the main branch. Because you develop using TDD and ATTD approaches, you know your source code is always working. This approach is deeply compatible with lean and agile values. It is also the one with the least waste of effort.

If your team decides to work with branches, make them short-lived!. See how you can do it in the Git Branches for the Impatient post.

Discarding Changes

You find the changes you made locally were not a good decision. No problem, you can erase these changes with:

Undo the last commit putting everything back into the staging area:

git reset --soft HEAD^

Undo last and remove changes:

git reset --hard HEAD^          (1)
1 Short form is git reset --hard.

You revert to the last save-committed set of files. Resetting with the hard option recursively discards all of your currently uncommitted (unstaged or staged) changes.

You want to restore just one file to its previous committed state.

git checkout --[filename]

Configuration Tips

You shall avoid the end of online character warnings by configuring git to handle them. The situation arises because Microsoft OS uses CRLF for the end of lines instead of CR.

You can configure git to handle it by running on Windows:

git config --global core.autocrlf true

Or on Linux and macOS:

git config --global core.autocrlf input

Thoughts

When using an IDE, consider the Editor Configuration approach for the end of line, indentation, and tabs versus spaces. All major integrated development environments support this configuration approach.

You can find a lot of information on Stack Overflow. Beware when reading the answers on Stack Overflow that Git commands have changed over time. Select new posts to find the best answers.

The nifty-gritty details can be found in the official Git documentation.

The Pro Git book can be downloaded from Git SCM.


1. Major platforms are Unix, Linux, macOS, and Microsoft Windows.