Article #1349: Git for FLTK Users

FLTK Apps FLTK Library Forums Links Login

[ Return to Articles | Show Comments | Submit Comment ]

Article #1349: Git for FLTK Users

Created at 04:39 Feb 08, 2014 by AlbrechtS

Last modified at 08:19 Jun 14, 2021

Short Introduction to Git

Git is a distributed version control system (DVCS), mainly used for software development. For more information about git please see the Git homepage and/or this Wikipedia article for an overview. Detailed information can be found in the online documentation. Personally I recommend the free online book Pro Git for further information. This book is also available for download in various formats.

Git Principles

Git is a distributed system. You download the entire repository (short: repo) with full history with 'git clone', then you work locally most of the time. Commits are done within the local storage until you decide to upload them to a server with 'git push'. However, there is no distinction between a "server" and a local repository since all repositories contain the entire history. You can also maintain different servers ("remotes") you fetch or pull from or push to. However, this is beyond the scope of this article.

Git for Subversion Users

This is a very short list of git commands that compares git commands with similar svn (subversion) commands. No details are given, though. Please see the docs.

git clone -- svn checkout (co)
git status -- svn status (st)
git log -- svn log
git pull -- svn update (up)
git branch -- n/a
git remote -- n/a
git checkout -- n/a [Note 1]
git add -- n/a [Note 2, 3]
git commit -- svn commit (ci) [Note 3]
git push -- svn commit [Note 3]

Note 1: 'git checkout' is used to switch branches within your local repository, whereas 'svn checkout' is used to download a subversion repo from a server.

Note 2: 'git add' and 'svn add' have different semantics, although some aspects are similar. See the docs.

Note 3: Not covered by this article, just for completeness: Git uses local storage when you run 'git add' and 'git commit' until you use 'git push' to upload your previous (local) commits to a server, whereas 'svn commit' uploads a single commit immediately.

Downloading FLTK

FLTK is now converted to git. This repository is on GitHub.

You can access the FLTK Repository directly on GitHub.

IMPORTANT NOTE: As of Dec 01, 2018 FLTK is no longer accessible via Subversion. You can view a short comparison of Subversion and Git commands in our Git Quick-Start Guide.

Cloning the FLTK Repository

$ git clone https://github.com/fltk/fltk.git [ fltk ]
$ cd fltk

The first command downloads the entire repository and stores it in the directory 'fltk' under your current working directory. The name 'fltk' is the default (derived from the repository name 'fltk.git'). The second argument in [] is optional: you can use another directory (w/o []), but the directory must not exist or it must be empty.

The directory fltk now contains the current FLTK sources and a subdirectory named .git with the entire software and history (the git repo).

The git clone command implicitly executes 'git checkout master', which means that the working directory is filled with the current state of the 'master' branch. The name 'master' is a git convention and usually means the main development branch. This is currently FLTK 1.4.x.

Using Development Branches or Stable Releases

You can check out a development branch or previous release with git checkout.
Examples:

(1) $ git checkout master
(2) $ git checkout branch-1.3
(3) $ git checkout release-1.3.7
(4) $ git checkout release-1.3.6rc2

will populate your working directory with the latest contents of

master: FLTK 1.4.x, the main development branch (not yet released)
branch-1.3: FLTK 1.3.x, the previous development branch (now in maintenance mode)
release-1.3.n: FLTK 1.3.n, a specific release (a git tag)
release-1.3.6rc2: FLTK 1.3.6rc2, a specific pre-release (a git tag)

To switch back to FLTK 1.4 (development branch) use

$ git checkout master

Stable releases are tagged with 'release-x.y.z[rcN]' where x, y, and z are the major, minor, and patch versions, respectively, and the optional 'rcN' denotes release candidate N. If you use a release tag, don't worry about the message "You are in 'detached HEAD' state. ...".
You can use the git branch and/or git tag commands to view the available branches and release tags:

$ git branch -a
$ git tag --list 'release-*'

We recommend to use FLTK 1.3 stable releases for "production" code. FLTK 1.4 (master) is "bleeding edge" development, in most aspects source compatible and usually also pretty stable. See below if you intend to use other FLTK versions, but these are either older (outdated) or alpha-state versions that have never been officially released.

Working with FLTK

You can now explore your FLTK working copy and use configure/make or CMake to generate one of many other build systems to build FLTK and your application.

Initial Setup

If you ever plan to commit changes in your repository, then you should read this paragraph. Otherwise go to the next paragraph "Updating your FLTK Repository".

Note that updating FLTK (i.e. committing your changes 'upstream') is generally not covered by this article, but anyway you should know: each commit contains a user name and a mail address. Git allows to configure this easily, and you should do it before your first commit, even if this is only a test.

$ git config [ --global ] user.name "My Name"
$ git config [ --global ] user.email "mail-address@example.com"

If you use the option --global, then this information is stored in your user profile and will be used for all git projects you have on this machine unless overridden by local settings. If you omit --global, then this is stored in the active git project (.git directory) and overrides any global settings.

Updating your FLTK Repository

To update your FLTK repository with all new features, i.e. to download the latest commits, there is a simple command that downloads the latest additions and updates to your working copy:

$ git pull

Your working copy should be clean before you use this, i.e. you should not have modified source files in it - otherwise you might get merge conflicts. Resolving merge conflicts is not covered by this article, since it is only intended for users to build their software with the FLTK version of their choice.

Status Informations about your FLTK Repository

The commands shown here give you some information about the current state of your repo. For further information please see the docs.

$ git status
$ git help <command>
$ git <command> --help 
$ git branch
$ git branch -v
$ git branch -a
$ git branch -r
$ git remote
$ git remote -v
$ git remote show origin
$ git tag -l
$ git tag --list

Notes:

Do not use 'git tag -v' -- this would create a tag named '-v'.
'git help <command>' and 'git <command> --help' show the man page of command '<command>'.

Other FLTK versions - NOT SUPPORTED

The main and only official, supported development version is FLTK 1.4, at the date of this writing this is not yet released. The latest stable release is FLTK 1.3.7.

If you need an older version, there are these official, but outdated branches available for FLTK 1.0 and FLTK 1.1:

branch-1.0
branch-1.1

Using unsupported alpha and beta development branches

There have been some beta development versions of FLTK 1.2 and FLTK 2.0, but these are NOT RECOMMENDED, have never been released, and are not officially supported. Note that branch-2.0 was the previous subversion "trunk".
There is another experimental, not supported, alpha-state version 3.0, which can be found in branch-3.0. As with branch-1.2 and branch-2.0 we do not plan to release this version officially. Use for testing only and at your own risk.
If you want to get these unsupported, experimental, and dormant branches you need to pull them from another Git repository which is currently not officially maintained (i.e. don't expect any commits). Using this 'legacy' repository is beyond the scope of this article.

This additional repository can be downloaded (cloned) from GitHub using this command:

$ git clone https://github.com/fltk/fltk-legacy.git [ fltk-legacy ]
$ cd fltk-legacy

Note: if you are an advanced user you may fetch the entire fltk-legacy repository into your normal fltk repository by adding the "remote" fltk-legacy and fetching from fltk-legacy. The two repositories are so far compatible, i.e. they contain the same subset of base commits (e.g. FLTK 1.0).

[ Listing ]

Comments

[ Submit Comment ]

From fire-eggs, 11:41 Aug 08, 2022 (score=3)

You can now explore your FLTK working copy and use configure/make or CMake to generate one of many other build systems to build FLTK and your application.

Don't forget the extra step of invoking 'autoconf' first, when cloning from github.
[ Reply ]

From AlbrechtS, 11:59 Aug 08, 2022 (score=3)

Thanks for this helpful comment. It should be noted, however, that running `autoconf' is only necessary if you build with configure/make rather than CMake.
[ Reply ]

From greg.ercolano, 10:29 Jun 09, 2021 (score=3)

Since folks might 'skim read', it might be appropriate to add under the "Cloning the FLTK Repository" a 'git checkout' command right after the 'git clone' to show how to get a specific release (added text in bold), e.g.

"""
$ git clone https://github.com/fltk/fltk.git [ fltk ]
$ cd fltk
$ git checkout release-1.3.5   -- checkout the 1.3.5 release

The third command 'git checkout release-1.3.5' checks out a particular release.
Use git tag --list 'release-*' to list all the releases available.

This way they'll know right away which release they're starting with, even if they don't read beyond that.
[ Reply ]

From AlbrechtS, 08:24 Jun 14, 2021 (score=3)

Thanks for the comment. I updated the article and included your suggested commands, but I reordered some text and rewrote a complete paragraph to make clear what users can or should use. I didn't want to point users directly at commands like 'git checkout release-1.3.5' as proposed w/o some more comments about their proper usage.
[ Reply ]