[[extend-git]]
=== Managing File and Configuration Revisions with Git

(((Tool,Git)))
(((Git tool,using)))

==== Goal

Use the Git revision control tool to manage revisions to files and configuration
on your site.

==== Prerequisite knowledge

* <<install-tools>>

* <<install-decide>>

* <<install-dev-sites>>

* How to set up a Git repository and find its _clone_ URL. For example, if
you want to use GitHub to host your repository, see
https://help.github.com/en/articles/create-a-repo[GitHub "Create a repo" page]
and
https://help.github.com/en/articles/which-remote-url-should-i-use[GitHub "Which remote URL should I use" page].

* How to open and use a command terminal window and a plain-text editor.

* To manage configuration, how to unpack and pack archive files (such as _.zip_
and _.tar.gz_).

==== Site prerequisites

* You must have downloaded the software for your site, using one of the methods
in <<install-decide>>. If you want to manage configuration, you must have
installed the software and have a running site.

* Git client software must be installed on your site's server. See
https://git-scm.com/[Git] for instructions.

* You must have a new repository created and know its Git clone URL.

==== Steps

===== Initializing the repository

Do these steps once, after creating a Git repository, to connect your local
directory to the repository and add the initial files to it.

. Open a command terminal window, and change to the directory where your site's
files are located. This is your "top" directory.

. Determine where your web root is. If the _core_, _modules_, and _themes_
directories are located directly in this directory, then you are in your web
root. If you have used Composer to download the software, then these files are
located inside the _web_ subdirectory (which is your web root).

. In a plain text editor, create a new file called _.gitignore_ in the top
directory (or edit it if it already exists). This file contains a list of files
and directories that Git should ignore (not add to the repository). For example,
the _settings.php_ file for your site should not be added to Git, because it
contains your database account information, and the media files uploaded to
your site (usually in _sites/default/files_) should not be in Git either -- the
objective is to have the software in the repository, not the site content.

. Make sure the following lines are in the _.gitignore_ file. If your web root
is not your top directory, check each of these to see if they need a prefix. For
example, _sites_ may need to be replaced with _web/sites_.
+
----
sites/*/settings*.php
sites/*/files
config
----

. Enter the following commands:
+
----
git init
git add -A
----

. Optionally, verify the list of files you will be adding to your Git repository
by entering this command and scrolling through the (very long) list:
+
----
git status
----

. Enter the following commands. You can substitute your own _commit message_ for
"Initial file add" if you wish, and you will need to substitute your own Git
clone URL for the URL in the second command:
+
----
git commit -m "Initial file add"
git remote add origin https://github.com/example-name/example-repo.git
git push -u origin master
----

. If you are using GitHub repository hosting, or another host with online
access, you can now go to your repository page and see that the files are there.

===== Updating files in the repository

Use these steps when you have updated, added, or deleted one or more files in
your site, in order to send the changes (_push_) to your repository.

. Open a command terminal window, and change to the directory where your site's
files are located.

. Check the list of files that have been added, changed, or deleted:
+
----
git status
----

. Optionally, for text files that have been changed (not images), look at the
differences between the new and old versions of the file:
+
----
git diff path/to/file.txt
----

. Stage all the changes for the next commit, and verify that they are staged:
+
----
git add -A
git status
----

. You can omit a particular file from the commit that you have already staged,
or add another file to the ones you have already staged. If a particular file
or directory keeps getting added by mistake, consider adding it to the
_.gitignore_ file so that it will be ignored by Git. Omit/add commands:
+
----
git reset HEAD path/to/file.txt
git add path/to/file.txt
----

. Commit and push your changes. Substitute something meaningful for the commit
message:
+
----
git commit -m "commit message here"
git push
----

. If you have other copies of your repository, update them by opening a command
window in the directory of each copy and running the following command:
+
----
git pull
----


===== Making a copy of the files in your repository

Follow these steps if you want to copy all the files in your repository to a
new location. For example, you might have both a local development copy of your
site and a production site, or several team members might all have local
copies of the site.

. Open a command window in the location where you want the files to be.

. Enter the following command, substituting your repository clone URL for the
URL, and the name of the subdirectory you want them in for _dirname_:
+
----
git clone https://github.com/example-name/example-repo.git dirname
----

===== Managing configuration in the repository

. Follow the instructions on <<extend-config-versions>> to export a complete
archive of your site's configuration.

. If you have not already initialized configuration in the repository, unpack
the configuration archive into a new directory, preferably above the web root
directory, and follow the instructions above to add these files to your
repository.

. After initializing, whenever your site configuration changes, export and
unpack the configuration archive in the same location. Follow the instructions
above to update these files in your repository.

. To import updated configuration to another site, make an archive of the
configuration directory from your repository. Then follow the instructions on
<<extend-config-versions>> to upload and import this archive into the site.


// ==== Expand your understanding

==== Related concepts

<<install-dev-sites>>

// ==== Videos

// ==== Additional resources


*Attributions*

Adapted and edited by https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon] from
https://www.drupal.org/node/803746["Building a Drupal site with Git"],
copyright 2000-2019 by the individual contributors to the
https://www.drupal.org/documentation[Drupal Community Documentation].
