Article #1349: Git for FLTK Users

     
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  |  Screenshots  ]
 

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 07:14 Dec 02, 2018

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 clone command implicitly does '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.

The latest stable version is FLTK 1.3.4 in 'branch-1.3'. Stable releases are tagged with 'release-X.Y.Z[rcN]' where X, Y, Z are the major, minor, and patch versions and the optional 'rcN' denotes release candidate N.

We recommend to use FLTK 1.3 for "production" code. FLTK 1.4 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

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.4-2 and we're planning to release 1.3.5 soon.

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).

Using other branches

$ git checkout branch-1.1
$ git checkout release-1.3.4

will populate your working directory with the latest contents of FLTK 1.1 or the released version 1.3.4, resp.. You can use any tag or branch for this command. If you use a tag, don't worry about the message "You are in 'detached HEAD' state. ...".

To switch back to FLTK 1.4 (the development version) use

$ git checkout master
Listing ]

Comments

Submit Comment ]
 
 

Comments are owned by the poster. All other content is copyright 1998-2018 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to 'erco@seriss.com'.