Download the LAMMPS source with git
-----------------------------------

LAMMPS development is coordinated through the "LAMMPS GitHub site".
If you clone the LAMMPS repository onto your local machine, it has
several advantages:

* You can stay current with changes to LAMMPS with a single git
  command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
  LAMMPS.  For that, you should first create your own :doc:`fork on
  GitHub <Howto_github>`, though.

You must have `git <git_>`_ installed on your system to use the
commands explained below to communicate with the git servers on
GitHub.  For people still using subversion (svn), GitHub also
provides `limited support for subversion clients <svn_>`_.

.. note::

   As of October 2016, the official home of public LAMMPS development is
   on GitHub.  The previously advertised LAMMPS git repositories on
   git.lammps.org and bitbucket.org are now offline or deprecated.

.. _git: https://git-scm.com
.. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github

You can follow the LAMMPS development on 4 different git branches:

* **release**  :  this branch is updated with every patch or feature release;
  updates are always "fast-forward" merges from *develop*
* **develop**  :  this branch follows the ongoing development and
  is updated with every merge commit of a pull request
* **stable**   :  this branch is updated from the *release* branch with
  every stable release version and also has selected bug fixes with every
  update release when the *maintenance* branch is merged into it
* **maintenance**  :  this branch collects back-ported bug fixes from the
  *develop* branch to the *stable* branch. It is used to update *stable*
  for update releases and it synchronized with *stable* at each stable release.

To access the git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:

.. code-block:: bash

   git clone -b release https://github.com/lammps/lammps.git mylammps

where "mylammps" is the name of the directory you wish to create on
your machine and "release" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)

.. admonition:: Saving time and disk space when using ``git clone``

   The complete git history of the LAMMPS project is quite large because
   it contains the entire commit history of the project since fall 2006,
   which includes the time when LAMMPS was managed with subversion.
   This includes a few commits that have added and removed some large
   files (mostly by accident).  If you do not need access to the entire
   commit history (most people don't), you can speed up the "cloning"
   process and reduce local disk space requirements by using the
   *--depth* git command line flag.  That will create a "shallow clone"
   of the repository, which contains only a subset of the git history.
   Using a depth of 1000 is usually sufficient to include the head
   commits of the *develop*, the *release*, and the *maintenance*
   branches.  To include the head commit of the *stable* branch you may
   need a depth of up to 10000.  If you later need more of the git
   history, you can always convert the shallow clone into a "full
   clone".

Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be generated
from the content provided in ``doc/src`` by typing ``make html`` from
the ``doc`` directory.

After initial cloning, as bug fixes and new features are added to
LAMMPS you can stay up-to-date by typing the following git commands
from within the "mylammps" directory:

.. code-block:: bash

   git checkout release      # not needed if you always stay in this branch
   git checkout stable       # use one of these 4 checkout commands
   git checkout develop      # to choose the branch to follow
   git checkout maintenance
   git pull

Doing a "pull" will not change any files you have added to the LAMMPS
directory structure.  It will also not change any existing LAMMPS files
you have edited, unless those files have changed in the repository.  In
that case, git will attempt to merge the changes from the repository
file with your version of the file and tell you if there are any
conflicts.  See the git documentation for details.

If you want to access a particular previous release version of LAMMPS,
you can instead "check out" any version with a published tag. See the
output of ``git tag -l`` for the list of tags.  The git command to do
this is as follows.

.. code-block:: bash

   git checkout tagID

Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout release`` (or
check out any other desired branch) first.

Once you have updated your local files with a ``git pull`` (or ``git
checkout``), you still need to re-build LAMMPS if any source files have
changed.  How to do this depends on the build system you are using.

.. tabs::

   .. tab:: CMake build

      Change to your build folder and type:

      .. code-block:: bash

         cmake . --build

      CMake should auto-detect whether it needs to re-run the CMake
      configuration step and otherwise redo the build for all files
      that have been changed or files that depend on changed files.
      In case some build options have been changed or renamed, you
      may have to update those by running:

      .. code-block:: bash

         cmake .

      and then rebuild.

   .. tab:: Traditional make

      Switch to the src directory and type:

      .. code-block:: bash

         make purge             # remove any deprecated src files
         make package-update    # sync package files with src files
         make foo               # re-build for your machine (mpi, serial, etc)

      to enforce consistency of the source between the src folder
      and package directories.  This is OK to do even if you don't
      use any packages. The ``make purge`` command removes any deprecated
      src files if they were removed by the update from a package
      subdirectory.

      .. warning::

         If you wish to edit/change a src file that is from a package,
         you should edit the version of the file inside the package
         subdirectory with src, then re-install the package.  The
         version in the source directory is merely a copy and will be
         wiped out if you type "make package-update".

.. admonition:: Git protocols
   :class: note

   The servers at github.com support the "https" access protocol for
   anonymous, read-only access.  If you have a suitably configured
   GitHub account, you may also use SSH protocol with the URL
   ``git@github.com:lammps/lammps.git``.

The LAMMPS GitHub project is currently overseen by Axel Kohlmeyer
(Temple U, akohlmey at gmail.com).
