forked from lijiext/lammps
365 lines
15 KiB
HTML
365 lines
15 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>LAMMPS GitHub tutorial — LAMMPS documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
|
|
|
|
|
|
|
|
<link rel="top" title="LAMMPS documentation" href="index.html"/>
|
|
|
|
|
|
<script src="_static/js/modernizr.min.js"></script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-nav-search">
|
|
|
|
|
|
|
|
<a href="Manual.html" class="icon icon-home"> LAMMPS
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="Manual.html">LAMMPS</a>
|
|
</nav>
|
|
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="Manual.html">Docs</a> »</li>
|
|
|
|
<li>LAMMPS GitHub tutorial</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="http://lammps.sandia.gov">Website</a>
|
|
<a href="Section_commands.html#comm">Commands</a>
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<div class="section" id="lammps-github-tutorial">
|
|
<h1>LAMMPS GitHub tutorial</h1>
|
|
<div class="section" id="written-by-stefan-paquay">
|
|
<h2>written by Stefan Paquay</h2>
|
|
<hr class="docutils" />
|
|
<p>This document briefly describes how to use GitHub to merge changes
|
|
into LAMMPS using GitHub. It assumes that you are familiar with
|
|
git. You may want to have a look at the <a class="reference external" href="http://git-scm.com/book/">Git book</a> to reacquaint yourself.</p>
|
|
</div>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="making-an-account">
|
|
<h1>Making an account</h1>
|
|
<p>First of all, you need a GitHub account. This is fairly simple, just
|
|
go to <a class="reference external" href="https://github.com">GitHub</a> and create an account by clicking
|
|
the <a href="#id1"><span class="problematic" id="id2">``</span></a>Sign up for GitHub’’ button. Once your account is created, you
|
|
can sign in by clicking the button in the top left and filling in your
|
|
username or e-mail address and password.</p>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="forking-the-repository">
|
|
<h1>Forking the repository</h1>
|
|
<p>To get changes into LAMMPS, you need to first fork the repository. At
|
|
the time of writing, LAMMPS-ICMS is the preferred fork. Go to <a class="reference external" href="https://github.com/lammps/lammps">LAMMPS on GitHub</a> and make sure branch is
|
|
set to <a href="#id3"><span class="problematic" id="id4">``</span></a>lammps-icms’‘, see the figure below.</p>
|
|
<img alt="_images/tutorial_branch.png" class="align-center" src="_images/tutorial_branch.png" />
|
|
<p>Now, click on fork in the top right corner:</p>
|
|
<img alt="_images/tutorial_fork.png" class="align-center" src="_images/tutorial_fork.png" />
|
|
<p>This will create your own fork of the LAMMPS repository. You can make
|
|
changes in this fork and later file <em>pull requests</em> to allow the
|
|
upstream repository to merge changes from your own fork into the one
|
|
we just forked from. At the same time, you can set things up, so you
|
|
can include changes from upstream into your repository.</p>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="adding-changes-to-your-own-fork">
|
|
<h1>Adding changes to your own fork</h1>
|
|
<p>Before adding changes, it is better to first create a new branch that
|
|
will contain these changes, a so-called feature branch.</p>
|
|
<div class="section" id="feature-branches">
|
|
<h2>Feature branches</h2>
|
|
<p>Since LAMMPS is such a big project and most user contributions come in
|
|
small portions, the most ideal workflow for LAMMPS is the so-called
|
|
<a href="#id5"><span class="problematic" id="id6">``</span></a>Feature branch’’ workflow. It is explained in great detail here:
|
|
<a class="reference external" href="https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow">feature branch workflow</a>.</p>
|
|
<p>The idea is that every new feature for LAMMPS gets its own
|
|
branch. This way, it is fairly painless to incorporate new features
|
|
into the upstream repository. I will explain briefly here how to do
|
|
it. In this feature branch, I will add a USER-package.</p>
|
|
<p>I assume that git is installed on the local machine and you know how
|
|
to use a command line.</p>
|
|
<p>First of all, you need to clone your own fork of LAMMPS:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git clone https://github.com/<your user name>/lammps.git
|
|
</pre></div>
|
|
</div>
|
|
<p>You can find the proper url to the right of the “HTTPS” block, see figure.</p>
|
|
<img alt="_images/tutorial_https_block.png" class="align-center" src="_images/tutorial_https_block.png" />
|
|
<p>The above command copies (<a href="#id7"><span class="problematic" id="id8">``</span></a>clones’‘) the git repository to your local
|
|
machine. You can use this local clone to make changes and test them
|
|
without interfering with the repository on github. First, however, it
|
|
is recommended to make a new branch for a particular feature you would
|
|
like added to LAMMPS. In this example, I will try adding a new
|
|
USER-package called USER-MANIFOLD.</p>
|
|
<p>To create a new branch, run the following git command in your repository:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git checkout -b add-user-manifold
|
|
</pre></div>
|
|
</div>
|
|
<p>The name of this new branch is “add-user-manifold” in my case. Just
|
|
name it after something that resembles the feature you want added to
|
|
LAMMPS.</p>
|
|
<p>Now that you’ve changed branches, you can edit the files as you see
|
|
fit, add new files, and commit as much as you would like. Just
|
|
remember that if halfway you decide to add another, unrelated feature,
|
|
you should switch branches!</p>
|
|
<p>After everything is done, add the files to the branch and commit them:</p>
|
|
<pre class="literal-block">
|
|
$ git add src/USER-MANIFOLD examples/USER/manifold/
|
|
$ git add doc/fix_nv<em>t,e</em>_manifold_rattle.txt
|
|
$ git add doc/fix_manifoldforce.txt doc/user_manifolds.txt
|
|
</pre>
|
|
<p>After the files are added, the change should be comitted:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git commit -m 'Added user-manifold package'
|
|
</pre></div>
|
|
</div>
|
|
<p>The “-m” switch is used to add a message to the commit. Use this to
|
|
indicate what type of change was commited.</p>
|
|
<div class="section" id="wisdom-by-axel">
|
|
<h3>Wisdom by Axel:</h3>
|
|
<p><em>“Do not use “git commit -a”. the -a flag will automatically include
|
|
*all</em> modified or new files. mercurial does that and it find it
|
|
hugely annoying and often leading to accidental commits of files you
|
|
don’t want. use git add, git rm, git mv for adding, removing,
|
|
renaming and then git commit to finalize the commit. personally, i
|
|
find it very convenient to use the bundled gui for commits, i.e. git
|
|
gui. typically, i will do git add and other operations, but then
|
|
verify and review them with git gui. git gui also allows to do
|
|
line-by-line unstaging and other convenient operations.”*</p>
|
|
<p>After the commit, the changes can be pushed to the same branch on GitHub:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git push
|
|
</pre></div>
|
|
</div>
|
|
<p>Git will ask you for your user name and password on GitHub if you have
|
|
not configured anything. If you correctly type your user name and
|
|
password, the change should be added to your fork on GitHub.</p>
|
|
<p>If you want to make really sure you push to the right repository
|
|
(which is good practice), you can provide it explicitly:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git push origin
|
|
</pre></div>
|
|
</div>
|
|
<p>or using an explicit URL:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git push git@github.com:Pakketeretet2/lammps.git
|
|
</pre></div>
|
|
</div>
|
|
<p>After that, you can file a new pull request based on this
|
|
branch. GitHub will now look like this:</p>
|
|
<img alt="_images/tutorial_pull_request_feature_branch1.png" class="align-center" src="_images/tutorial_pull_request_feature_branch1.png" />
|
|
<p>Make sure that the current branch is set to the correct one, which, in
|
|
this case, is “add-user-manifold”. Now click “New pull request”. If
|
|
done correctly, the only changes you will see are those that were made
|
|
on this branch, so in my case, I will see nothing related to
|
|
$mathrm*pair_dzugatov*.$</p>
|
|
<p>This will open up a new window that lists changes made to the
|
|
repository. If you are just adding new files, there is not much to do,
|
|
but I suppose merge conflicts are to be resolved here if there are
|
|
changes in existing files. If all changes can automatically be merged,
|
|
green text at the top will say so and you can click the “Create pull
|
|
request” button, see image.</p>
|
|
<img alt="_images/tutorial_pull_request2.png" class="align-center" src="_images/tutorial_pull_request2.png" />
|
|
<p>After this you have to specify a short title and a comment with
|
|
details about your pull request. I guess here you write what your
|
|
modifications do and why they should be incorporated upstream. After
|
|
that, click the “Create pull request” button, see image below.</p>
|
|
<img alt="_images/tutorial_pull_request3.png" class="align-center" src="_images/tutorial_pull_request3.png" />
|
|
<p>Now just write some nice comments, click “Comment”, and that is it. It
|
|
is now up to the maintainer(s) of the upstream repository to
|
|
incorporate the changes into the repository and to close the pull
|
|
request.</p>
|
|
<img alt="_images/tutorial_pull_request4.png" class="align-center" src="_images/tutorial_pull_request4.png" />
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="additional-changes">
|
|
<h1>Additional changes</h1>
|
|
<p>Before the pull request is accepted, any additional changes you push
|
|
into your repository will automatically become part of the pull
|
|
request.</p>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="after-a-merge">
|
|
<h1>After a merge</h1>
|
|
<p>When everything is fine the feature branch is merged into the LAMMPS
|
|
repositories:</p>
|
|
<img alt="_images/tutorial_merged.png" class="align-center" src="_images/tutorial_merged.png" />
|
|
<p>Now one question remains: What to do with the feature branch that got
|
|
merged into upstream?</p>
|
|
<p>It is in principle safe to delete them from your own fork. This helps
|
|
keep it a bit more tidy. Note that you first have to switch to another
|
|
branch!</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git checkout lammps-icms
|
|
$ git pull lammps-icms
|
|
$ git branch -d add-user-manifold
|
|
</pre></div>
|
|
</div>
|
|
<p>If you do not pull first, it is not really a problem but git will warn
|
|
you at the next statement that you are deleting a local branch that
|
|
was not yet fully merged into HEAD. This is because git does not yet
|
|
know your branch just got merged into lammps-icms upstream. If you
|
|
first delete and then pull, everything should still be fine.</p>
|
|
<p>Finally, if you delete the branch locally, you might want to push this
|
|
to your remote(s) as well:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ git push origin :add-user-manifold
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2013 Sandia Corporation.
|
|
</p>
|
|
</div>
|
|
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT:'./',
|
|
VERSION:'',
|
|
COLLAPSE_INDEX:false,
|
|
FILE_SUFFIX:'.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
|
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
|
|
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
|
|
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.StickyNav.enable();
|
|
});
|
|
</script>
|
|
|
|
|
|
</body>
|
|
</html> |