ArtiSynth Installation Guide for Windows

To compile or run ArtiSynth from a terminal window, the java and javac commands of your JDK must be visible there, and must supersede any other Java installations. To check this, open a CMD window and run the command

 > javac -version

The output should match the version of the installed JDK. The JDK installer usually takes care of this. If it does not, or if the command javac is not found, then one fix is to add the folder <JDK_HOME>\bin to your system Path, as described in Section 14.1, where <JDK_HOME> is the JDK home folder described above. It should be added ahead of any other Java installations that might be specified. To see the current contents of the Path, open a CMD window and run the command

 > echo %PATH%

If you are using an integrated development environment (IDE), such as Eclipse (Section 13), and want it to use your JDK instead of its own version of Java, you should also configure it to do so. Instructions for Eclipse are given in Section 13.1.1.

Once ArtiSynth is downloaded and unzipped, it should be possible to run it immediately by using a file browser to locate and then double click on the batch file

  <ARTISYNTH_HOME>\bin\artisynth.bat

You can create a shortcut to this batch file (by right clicking on it and selecting Create Shortcut), and then place the shortcut in either the START menu or on the Desktop. However, the file itself must remain in <ARTISYNTH_HOME>\bin.

ArtiSynth can also be run from a terminal window.

To do this, open a terminal (CMD) window, set the current folder to <ARTISYNTH_HOME>, and run the command bin\artisynth:

 > cd <ARTISYNTH_HOME>
 > bin\artisynth

If you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.1), then ArtiSynth can be run from a terminal window with the simple command

 > artisynth

regardless of the current folder.

Details on how to load and run demo models are given in Section 7.

A precompiled ArtiSynth distribution can also be imported into an integrated development environment (IDE), such as Eclipse, to facilitate compilation and execution. To import ArtiSynth into Eclipse, follow the instructions in Section 13.2, using <ARTISYNTH_HOME> as the project directory.

If you are planning to use the Eclipse IDE (Section 13), you can install from GitHub directly into Eclipse. Directions on installing Eclipse and configuring it for ArtiSynth development are given in Section 13.1. Once Eclipse is installed, ArtiSynth can be installed as follows:

1. 1.

   From the main menu, select “File > Import ...”. This will cause an Import dialog to appear, as shown below. Open “Git > Projects from Git”, and then click Next.

   
2. 2.

   In the next dialog, choose Clone URI, and click Next.

3. 3.

   A Source Git Repository dialog will appear, as shown below. In the URI field at the top, enter
   https://github.com/artisynth/artisynth_core.git
   This will automatically fill the Host and Repository path fields. Click Next.

   
4. 4.

   A Branch Selection dialog will appear. If multiple branches are available, make sure that only master is selected. Click Next.

5. 5.

   A Local Destination dialog will appear as shown below, indicating the folder into which ArtiSynth will be placed locally. Use the default location, or edit it to the desired location. This will be your ArtiSynth home folder, and will be referred to later in this document as <ARTISYNTH_HOME>. Click Next.

   
6. 6.

   ArtiSynth will now be downloaded; this may take a few minutes, depending on your network connection speed. Another dialog will appear, asking you to select a project import wizard. Leave the default (“Import existing Eclipse projects”) selected, and click Next.

7. 7.

   An Import Projects dialog will appear, confirming that you want to import artisynth_core. Leave everything as is, and click Finish.

artisynth_core has now been imported into Eclipse as a project, and Eclipse will begin to build it, first by automatically downloading the Java and native libraries that ArtiSynth needs. (These are not included in the GitHub repository because they are quite large.) The download can be on the order of 200 Mbytes, and so may take up to several minutes, depending on network speed. Its progress is shown in Eclipse’s Console view, at the bottom of the Eclipse window:

On some versions of Eclipse, the console view may need to be opened explicitly, by selecting Window > Show View > Console from the main menu.

When the download is complete, the console will display the message LIBRARIES UPDATED SUCCESSFULLY:

Eclipse will then compile ArtiSynth, with the progress bar at the lower right showing compilation progress.

If some libraries could not be downloaded (e.g., because of a network problem), the console will say so, and the artisynth_core project will be marked with errors. After checking your network connection, you can retry the download by selecting Run > External Tools > UpdateArtisynthLibs from the main menu, or Project > Clean....

ArtiSynth is currently compiled to be compliant with Java 8, regardless of the Java version. The Eclipse settings supplied in artisynth_core\.settings ensure this. This will be raised to Java 21 in the near future.

After compilation is complete, ArtiSynth can be run by selecting artisynth_core in the Package Explorer and choosing Run > Run from the main menu:

Alternatively, you can click the small arrow beside the green Run button in the Eclipse toolbar and choose ArtiSynth. Either way works by invoking a predefined launch configuration named ArtiSynth. In some cases, one may wish to adjust the launch configuration to set environment variables, command line arguments, or Java JVM arguments that affect how ArtiSynth behaves. Instructions for doing so are contained in Sections 13.4 and 13.5.

It is also possible to run ArtiSynth from either a file browser or a terminal window, as described in Sections 5.1 and 5.2, respectively. Details on how to load and run demo models are given in Section 7.

Git for Windows is an application that provides the user with a terminal window interface that can be used for entering Git commands. Users can choose between GitBash, which provides a Unix-like bash shell, or GitCMD, which provides a Windows CMD shell. GitBash has several advantages, such as allowing users to easily set environment variables in a .bashrc file (Section 14.2.3), and supplying a number of Unix-like commands that can be convenient for tasks other than those involving Git.

At the time of this writing, Git for Windows can be installed from git-scm.com/download/win.

Once installed, ArtiSynth can then be installed and compiled by opening a GitBash window and entering the following commands (where the ‘$’ character indicates the GitBash prompt and should not be entered):

The first line simply sets the current folder to the one under which you wish to install ArtiSynth, as indicated by /path/to/install. (Note that GitBash follows the Unix convention of using forward slash (’/’) instead of backslash (’\’) to separate files.) The git clone command then downloads ArtiSynth and extracts it to a folder named artisynth_core, so that the ArtiSynth installation directory (or <ARTISYNTH_HOME>) is/path/to/install/artisynth_core. The updateArtisynthLibs command fetches additional libraries that are not included in the GitHub repository for space reasons, and the bin/compile command on the last line is an ArtiSynth-supplied utility that compiles all .java files located under the current folder. The updateArtisynthLibs and compile commands use the java and javac commands of your JDK, which must be visible from the command window (Section 4.1).

If you have GNU make installed on your system, then you can use that instead of the compile command, replacing

with

make also downloads any missing libraries automatically, so when using it, the updateArtisynthLibs step can be omitted.

ArtiSynth is currently compiled to be compliant with Java 8, regardless of the JDK version. The make and compile commands described above ensure this. This will be raised to Java 21 in the near future.

The make and compile commands automatically determine the Java classpath needed to compile ArtiSynth, consisting of the classes folder plus the .jar files listed in lib\LIBRARIES. If you have set the CLASSPATH environment variable, its entries are appended to this, except for any that refer to the lib folder. See Sections 10.1.2 and 14.2.

Once built, ArtiSynth can then be run (from within artisynth_core) using the command

For convenience, if you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.1), then ArtiSynth can be run independently of the current directory using the simple command

 % artisynth

ArtiSynth can also be installed and compiled using GitCMD, with an analogous command sequence:

The only real difference is using backslash (’\’) instead of forward slash (’/’) as a file separator.

Details on how to load and run demo models are given in Section 7.

Note that once you have installed ArtiSynth, you still have the option to later import it into an IDE such as Eclipse. For Eclipse specifically, this is done by importing it as an external project, as described in Section 13.2.

After ArtiSynth starts up, you can load and run demonstration models. Do this by selecting Models > Demos from the main menu and choosing a demo model (Figure 1).

Once a model is loaded, it will appear in the viewer, and simulation can be controlled using the “play” controls located at the upper right of the application window:

From left to right, these are: step size control, which controls the simulation step size (in seconds); current simulation time (in seconds); and the reset, skip-back, play/pause, single-step, skip-forward and stop-all buttons. Starting and stopping a simulation is done by clicking play/pause, while reset resets the simulation to time 0. The single-step button advances the simulation by one time step. The stop-all button will also stop the simulation, as well as any Jython commands or scripts that are running.

Detailed information on how to use the ArtiSynth GUI for model visualization, navigation and simulation control is given in the ArtiSynth User Interface Guide.

Figure 2 shows ArtiSynth with the Spring Net demo loaded.

It is possible to load models in several ways:

• •

  Using a model menu entry, as described above;

• •

  Specifying the Java class describing the model (“Load from class ...” from the Models menu);

• •

  Specifying a .art file containing a text representation of the model (“Load model ...” from the File menu);

• •

  Reloading a recently loaded model (“Load recent” from the Models menu).

It is also possible to configure ArtiSynth to load a specific model when it starts up; see “Loading, Simulating and Saving Models” in the ArtiSynth User Interface Guide. The model menu can also be customized, as described in “Customizing the Model Menu”.

The ArtiSynth user interface provides a variety of tools for exploring and interacting with models, as described in depth in the ArtiSynth User Interface Guide, including:

• •

  3D viewers with grids and clipping planes;

• •

  Component selection using either a viewer or a tree-based navigation panel;

• •

  Property inspection and editing for selected components;

• •

  3D fixtures for translating, rotating and applying forces to models and their components;

• •

  A timeline for viewing and organizing input/output data streams known as probes;

• •

  Some simple model editing, including the ability to interactively delete components and add marker points;

• •

  Making movies from simulations.

If you are running ArtiSynth from a terminal window (Section 5.2) or GitBash (Section 6.2) then you can supply it with command line arguments to control different aspects of its behavior. A full list of these can be seen by running artisynth with the -help option:

 > artisynth -help

Descriptions of these options appear in various places within the ArtiSynth documentation. For example, one commonly used option is -model <modelClassName>, which instructs ArtiSynth to preload a model associated with a given class name:

 > artisynth -model artisynth.demos.mech.SpringMeshDemo

If you are running under Eclipse, command line arguments can be set in the launch configuration, as described in Section 13.5.

A model should be implemented inside a Java package, which will contain the model class, and perhaps other supporting classes used to implement it. The package is defined by the package statement at the beginning of each .java file. For the MyModel example above, the package is artisynth.models.mymodels.

Java enforces certain rules for how its source code is organized. In particular, all the .java files associated with a specific package must be placed in the same folder, which in turn must be located in a folder tree that reflects the package hierarchy. For example, source code for the package pack.foo.bar must be placed in a folder whose path (relative to the top of the source tree) is pack\foo\bar. For the MyModel example, MyModel.java must be placed in a folder artisynth\models\mymodels relative to the top of the source tree.

The source code tree for ArtiSynth is rooted at <ARTISYNTH_HOME>\src. It already contains a large number of model classes located in packages such as artisynth.demos.mech, whose source code is therefore located at

<ARTISYNTH_HOME>\src\artisynth\demos\mech

The easiest way to add your own model to ArtiSynth is to simply add the source code for its package to the appropriate location under <ARTISYNTH_HOME>\src. For MyModel, the source code would therefore be placed in

<ARTISYNTH_HOME>\src\artisynth\models\mymodels

Since the ArtiSynth source tree already contains the (empty) folder artisynth\models, in this case it would only be necessary to add the mymodels folder below it.

Multiple models may be placed in any given package. For example, artisynth.demos.tutorial contains a large number of models used as examples for the Modeling Guide.

When source code is added or modified within the ArtiSynth source tree, it needs to be compiled. How this is done depends on your development environment.

If you are using Eclipse and automatic building is enabled for a project (such as artisynth_core), compilation will occur automatically whenever that project’s .java files are modified. To see if automatic building is enabled, select the project in the Package Explorer, open the Project menu and check Build Automatically. If automatic building is not enabled, the project can be built by selecting Build Project.

If you add or edit source files from outside Eclipse, for example by using an external text editor, then you need to refresh the project in order for Eclipse to notice the changes. To refresh, select the project in the Package Explorer, and then either right-click and choose Refresh, or simply hit the F5 key.

If you are compiling from the command line or GitBash, using either the make or compile commands described earlier, then running these in any given source folder will compile all the .java files contained below it. This will typically be faster than compiling the entire source tree by running make or compile from <ARTISYNTH_HOME>.

To be able to run compile from any folder, place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.1).

If you add a new package folder and want to run make from that folder, you will need to add a Makefile to it. The easiest way to do this is to simply copy an existing Makefile from another package and adjust the PACKAGE_NAME and ROOT_DIR entries; the number of ‘..’ entries in ROOT_DIR should equal the number of “up” steps needed to reach <ARTISYNTH_HOME>.

Once a model has been added to ArtiSynth, it is useful to be able to run it directly from the model menu, located under Models in the main menu bar.

By default, the model menu locates all models in the packages (and subpackages) of artisynth.demos andartisynth.models, and makes them available under the entries All demos > and All models >, respectively. Therefore, if your model is located in one of these packages, it will automatically appear in the Models menu. If your model is located in a different package, you can load it either by directly specifying its class path, or by customizing the Models menu. These options are described in the sections “Loading by class path” and “Customizing the Model Menu” of the ArtiSynth User Interface Guide.

How this is done depends on your development environment.

If you are running a precompiled release of ArtiSynth, then you will need to use the corresponding precompiled release of artisynth_models, which can be obtained from

  www.artisynth.org/Software/ModelsDownload

Download the distribution you want and unzip it in your desired location; the recommended spot is right next to artisynth_core.

artisynth_models comes preconfigured with Eclipse project files, and so can be immediately imported into Eclipse as an external project, as described in Section 13.2. To make the models visible to ArtiSynth when running from Eclipse, it will be necessary to add artisynth_models to the ArtiSynth launch configuration, as described in Section 13.7.

If you are running ArtiSynth from the command line or the artisynth.bat file, you will need to ensure that the class folder artisynth_models\classes is visible to ArtiSynth, as described in Section 10.2.

The latest development version of artisynth_models is available from GitHub at the URL

   https://github.com/artisynth/artisynth_models.git

An update may also change the libraries that ArtiSynth needs, as listed in the file <ARTISYNTH_HOME>\lib\LIBRARIES. Such changes are normally handled automatically:

• •

  In Eclipse, any new or changed libraries are downloaded the next time the project is built, as during installation (Section 6.1).

• •

  When compiling with make, any new or changed libraries are downloaded before compilation begins.

• •

  When ArtiSynth starts up, it checks that all the required libraries are present and downloads any that are missing.

In each case, older versions of the libraries, and libraries that are no longer needed, are removed from <ARTISYNTH_HOME>\lib.

Libraries can also be updated explicitly using the command updateArtisynthLibs located in <ARTISYNTH_HOME>\bin, which can be run from a terminal window:

 > cd <ARTISYNTH_HOME>
 > bin\updateArtisynthLibs

or, from within Eclipse, by selecting Run > External Tools > UpdateArtisynthLibs from the main menu. Selecting “Update libraries” from the ArtiSynth File menu, or running ArtiSynth with the -updateLibs option, will also check that the installed libraries match the latest versions on the ArtiSynth server.

If you have modified files in artisynth_core (or another ArtiSynth-supported project such as artisynth_models) which are also changed by the update, Git will refuse the pull, and list the files concerned.

If the pull was attempted using Team > Pull in Eclipse, then a Pull Problem box will appear (Figure 4). Clicking Details will provide further information, with the conflicting files listed after the words “Checkout conflict with files”.

If the pull was attempted on the command line, then the pull will fail with a message similar to

 error: Your local changes to the following files would be overwritten by merge:
         .classpath
         .project
         ArtiSynth.launch
 Please commit your changes or stash them before you merge.

Nothing is lost when this happens: your files and the codebase remain as they were. However, in order to proceed with the pull, you need to either discard the conflicting files, or attempt to merge them.

Eclipse is released quarterly, with versions named by year and month (e.g., 2026-09). Any recent version should work; the instructions below use 2026-09 as an example.

Eclipse can be downloaded from www.eclipse.org/downloads/packages. From this page, choose “Eclipse IDE for Java Developers”, Windows x86_64, which will download a file named

  eclipse-java-2026-09-R-win32-x86_64.zip

Unzip this into a convenient folder, such as for example:

  C:\eclipse\eclipse-2026-09

Open this folder with a file explorer, and you will see the eclipse application:

Click on this to open it. A dialog will appear, asking you to select a workspace folder (Figure 5). This is where Eclipse settings and project information will be stored. Unless you have another Eclipse already installed, the default location should be fine. (Remember also to check the “Use this as the default ...” box so that this query won’t appear every time you open Eclipse.) Next, click Launch. A welcome page will appear; close this. A “donate” panel may also appear; close this too. You should then see an empty Eclipse display, similar to Figure 6.

Let <PROJECT_DIR> denote the top-level folder of the project to be imported. (In the case of artisynth_core, this will also be <ARTISYNTH_HOME>.) Assuming that <PROJECT_DIR> contains an Eclipse .project file, you can import it into Eclipse as follows:

1. 1.

   From within Eclipse, choose “File > Import ...”.

2. 2.

   An Import dialog will appear. Select General > Existing Projects into Workspace and click Next.

3. 3.

   An Import Projects dialog will appear. In the field Select root directory, enter (or browse to) the parent folder of <PROJECT_DIR>. The project itself should now appear in the Projects box (Figure 9). (If other projects are contained in the parent folder, these will appear as well.) Make sure that the desired project is selected and then click Finish.

If Eclipse complains that "No projects are found to import", or does not otherwise show the project as available for import, then most likely the <PROJECT_DIR> folder does not contain a .project file.

ArtiSynth is run from Eclipse using the launch configuration named ArtiSynth, which is stored in the file ArtiSynth.launch in artisynth_core. Since this file is part of the ArtiSynth codebase, editing it (to set arguments or add projects, as described in the following sections) may later cause a Git pull to be refused (Section 12.2). It is therefore better to make a copy of the launch configuration and edit that instead:

1. 1.

   From the main menu, choose “Run > Run Configurations...” to open the Run Configurations dialog.

2. 2.

   In the left panel, under Java Application, right click on ArtiSynth and choose Duplicate.

3. 3.

   In the right panel, change the Name of the copy to something like MyArtiSynth.

4. 4.

   Select the Common tab, and make sure that Local file is selected under Save as, so that the copy is stored in your Eclipse workspace rather than in artisynth_core.

5. 5.

   Click Apply.

The copy can then be run from the Run Configurations dialog, or by clicking the small arrow beside the green Run button in the Eclipse toolbar and choosing it from the menu.

While it is generally not necessary to set environment variables in Eclipse, it may be useful to do this on occasion to control certain aspects of ArtiSynth’s operation. Directions on setting the environment variables are given in Section 13.4.1, and descriptions of the variables themselves may be found in Section 14.2.

If any environment variables have already been set externally in Windows (Sections 14.2.1 and 14.2.2), such that they are visible to Eclipse at start-up, then they do not need to be set in the launch configuration.

As described in Section 7.4, the artisynth command accepts command line arguments. To invoke these when running from Eclipse, it is necessary to set the desired arguments in the launch configuration, as described below.

Sometimes it may also be necessary to set JVM arguments, which control the Java virtual machine running ArtiSynth. An example of such an argument is -XX:MaxRAMPercentage=NN, which sets the maximum amount of memory available to the application to NN percent of the computer’s memory. For example, -XX:MaxRAMPercentage=50 allows ArtiSynth to use up to half of the computer’s memory. The default value is 25.

A project imported into Eclipse may depend on the packages and libraries found in other projects to compile properly. For example, ArtiSynth applications which are external to artisynth_core will nonetheless depend on artisynth_core. To ensure proper compilation, project dependencies should be added to each dependent project’s build path.

1. 1.

   Select the dependent project in the Package Explorer form.

2. 2.

   Right click and choose “Build Path > Configure Build Path...”

3. 3.

   In the right panel, select the Projects tab.

4. 4.

   Click the Add button, select the project dependencies, and click OK

5. 5.

   Click OK in the Java Build Path panel

The classes of external projects can be made visible to ArtiSynth by adding the projects themselves to the Classpath of the ArtiSynth launch configuration.

1. 1.

   From the main menu, choose “Run > Run Configurations...” to open a Run Configurations dialog.

2. 2.

   In the left panel, under Java Application, select your ArtiSynth launch configuration (preferably a copy of the default ArtiSynth configuration; see Section 13.3).

3. 3.

   In the right panel, select the Classpath tab.

4. 4.

   In the Classpath window, select User Entries, and then click the Add Projects button.

5. 5.

   In the Project Selection dialog, select the external projects that you wish to add. Generally, the boxes “Add exported entries ...” and “Add required projects ...” can be unchecked. Click OK.

6. 6.

   Close the Run Configurations dialog.

The system “Path” is a list of directories which the system searches in order to find executables. Adding a directory to the path allows executables contained in that directory to be called directly from a command window such as CMD.

1. 1.

   Open the Start search, enter “env”, and choose “Edit the system environment variables”.

2. 2.

   Click on Environment Variables.

3. 3.

   Under User variables (the top window), click on Path and click Edit. If Path does not exist, click New.

4. 4.

   In the Edit environment variable dialog, click New and enter the full path name for each directory you wish to add.

5. 5.

   Close each dialog by clicking OK.

For example, if ArtiSynth is installed at C:\artisynth\artisynth_core, then you would add the directory

  C:\artisynth\artisynth_core\bin

Most command windows and applications need to be restarted in order to get them to notice changes to Path.

This is a glossary of all the environment variables that are associated with building or running ArtiSynth. Often, the system can detect and set appropriate values for these automatically. In other cases, as noted in the above documentation, it may be necessary or desirable for the user to set them explicitly.

ARTISYNTH_HOME

The path name of the ArtiSynth installation folder.

CLASSPATH

A list of folders and/or JAR files, separated by semi-colons ‘;’, which Java uses to locate its class files.

Path

A list of folders, separated by semi-colons ‘;’, which the operating system uses to locate executable programs and applications. Placing <ARTISYNTH_HOME>\bin in Path (as described in Section 14.1) will allow you to run artisynth and related commands directly from a command window.

OMP_NUM_THREADS

Specifies the maximum number of processor cores that are available for multicore execution. If not set, the system uses the maximum number of cores available. Users can also set this number from within ArtiSynth by setting the configuration property numSolverThreads, either for the current session by choosing “Settings > Interaction ...” from the main menu, or for all sessions by choosing “Settings > Preferences ... > Interaction”.

Note that settings for most of the above can be derived from the value of ARTISYNTH_HOME.

ArtiSynth uses a set of libraries located under <ARTISYNTH_HOME>\lib. These include a number of JAR files, plus native libraries located in architecture-specific sub-folders (such as Windows64 for 64-bit Windows systems).

When ArtiSynth is installed from GitHub, these libraries are not part of the repository, but are downloaded from the ArtiSynth server. The required libraries are listed in the file <ARTISYNTH_HOME>\lib\LIBRARIES. This file is part of the repository, so that the system can always determine what libraries are needed for a particular version of the code. The classpath used to compile and run ArtiSynth is formed from the JAR files listed in LIBRARIES, rather than from all the JAR files in <ARTISYNTH_HOME>\lib.

Libraries are downloaded automatically, by Eclipse when it builds artisynth_core, by make, and by ArtiSynth itself when it starts up, as described in Section 12. When a library is replaced by a newer version, the older version is removed, as are libraries that are no longer needed (which are listed in the file <ARTISYNTH_HOME>\lib\OBSOLETE).

Do not add your own JAR files to LIBRARIES, or to <ARTISYNTH_HOME>\lib. Changing LIBRARIES may cause later Git pulls to be refused (Section 12.2). Instead, add them to the build path of your own project, or to the external class path (Section 10.2.2).

The EXTCLASSPATH file is stored in the user configuration folder (Section 9) and contains the entries for the external class path (Section 10.2.2). It is usually edited within ArtiSynth by selecting “External classpath ...” from the Settings menu but can also be edited directly. Each file entry describes a class folder or JAR file needed to run models external to the core ArtiSynth package. Entries are usually placed one per line, but multiple entries can be made on the same line if separated by semi-colons ‘;’.

The syntax rules for EXTCLASSPATH are:

1. 1.

   Entries on the same line should be separated semi-colons ‘;’.

2. 2.

   The ‘#’ character comments out all remaining characters to the end of line.

3. 3.

   The ‘$’ character can be used to expand environment variables.

4. 4.

   Any spaces present will be included in the entry name.

An example EXTCLASSPATH might look like this:

C:\research\artisynth_models\classes
C:\research\models\special.jar
$HOME\projects\crazy\classes

Git is a distributed source control management (SCM) system that is widely used in the software industry. A full discussion of Git is beyond the scope of this document, but a large literature is available online. Generally, when you clone a Git repository, you create a local copy of that repository on your machine, along with a checked out working folder containing the most recent version of the code (which is referred to as the HEAD).

Unlike client/server SCMs, Git is distributed, with users maintaining their own private copies of a repository. This allows a great deal of flexibility in usage, but also adds an extra “layer” to the workflow: when you “checkout” from a repository or “commit” to it, you do so with respect to your own local copy of that repository, not the original (origin) repository from which you performed the original clone. The process of merging in changes from the origin to the local repository is known as “pulling”, while committing changes from the local repository back to the origin is known as “pushing”.

There is also another layer of interaction when you commit changes to the local repository: you first add them to a staging area (also known as the “index”), and then commit them using the commit command.

A very simple workflow for a typical ArtiSynth user is summarized below. The actions are described in command-line form, but the same commands can generally be issued through Eclipse or other interfaces. First, clone the most recent version of the ArtiSynth repository on GitHub:

  git clone https://github.com/artisynth/artisynth_core.git [<dir>]

This will create a local copy of the GitHub repository, along with a checked out “working copy”, in the folder specified by <dir>, or in artisynth_core if <dir> is omitted. The repository itself will be located in a sub-folder called .git.

Other Git repositories can be cloned in a similar manner. If the repository has read access restrictions, then when performing a checkout it may also be necessary to specify a user name for which the repository has granted read access. This is typically done by embedding the user name in the URL, as in (for example):

https://user@host.xz/path/to/repo.git

Later, to fetch the latest updates from the GitHub repository and merge them into your working copy, from within the working copy folder you can do

  git pull

If you make changes to some files in your working copy and wish to commit these to your local repository, you first add (or remove them) from the staging area using commands such as:

  git add <fileName>    # add a new (or modified) file
  git add *             # add all files
  git rm <fileName>     # remove a file

and then commit them to your local repository using

  git commit -m "commit message"

Note that you can also add modified files and commit them using the single command

  git commit -a -m "commit message"

To see the current status of the files in your working copy and the staging area, use the command

  git status

and to see the commit history for particular files or folders, use

  git log [ <filename> ... ]

Finally, to push your changes back to the GitHub repository (assuming you have permission do so), you would do so using the command

  git push origin master

Note that the above commands all have various options not mentioned. There are also numerous topics that haven’t been discussed, including the creation and merging of branches, but there are many useful online resources that describe these in detail. Some current references include

   https://git-scm.com/docs
   https://rogerdudler.github.io/git-guide