// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \page creator-vcs-git.html
    \previouspage creator-reference.html
    \nextpage

    \ingroup creator-reference-vcs

    \title Using Git

    \quotation
    \l {Use Git}{How to: Use Git}
    \endquotation

    \summary {Additional Git functions.}

    \l{Git Downloads}{Git} is a fast decentralized version control system.
    Git is available for Windows, Linux, and \macos.

    You can use the \l{Gerrit Code Review} tool for projects that use Git.

    \section1 Getting started with Git

    \generatelist creator-how-to-git-general

    \section1 Working with the current file

    To work with the current file, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Current File}.

    \generatelist creator-how-to-git-current-file

    \section1 Working with the current project

    To work with the current project, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Current Project Directory}.

    \generatelist creator-how-to-git-current-project

    \section1 Working with local repositories

    To work with the local repository, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Local Repository}.

    \generatelist creator-how-to-git-local-repository

    \section1 Working with remote repositories

    To work with remote repositories, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository}.

    \generatelist creator-how-to-git-remote-repository

    \section2 Managing remote repositories

    To manage remote repositories available in Git, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository} >
    \uicontrol {Manage Remotes}. Double-click the names and URLs of the remote
    repositories to edit them.

    The following operations are supported:

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li \uicontrol{Refresh}
            \li Refresh the list of remote repositories.
        \row
            \li \uicontrol{Add}
            \li Add a new remote repository.
        \row
            \li \uicontrol{Fetch}
            \li Fetch all the branches and change information from a remote
                repository.
        \row
            \li \uicontrol Push
            \li Push committed changes to the remote repository.
        \row
            \li \uicontrol{Remove}
            \li Remove a remote repository.
    \endtable

    \sa {Use Git}{How to: Use Git}, {Compare files},
    {Set up version control systems}, {Version Control Systems}
*/

/*!
    \page creator-how-to-git-first-commit.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-general

    \title Commit your first change

    When working with Git, you typically check and stage you local changes,
    commit them to the local repository, and then push them to a remote
    repository (\e origin).

    Before you start, set up Git in \preferences > \uicontrol {Version Control}
    > \uicontrol {General}.

    \section1 Commit to a new repository

    To commit and push your first change to a new repository:

    \list 1
        \li To start tracking changes, go to \uicontrol Tools > \uicontrol Git,
            and then select \uicontrol {Create Repository}.
        \li To view local changes, go to \uicontrol Tools > \uicontrol Git >
            \uicontrol {Local Repository} and select \uicontrol {Diff}.
            \image {qtcreator-git-diff-repository.webp} {Git Diff Repository view}
            \caption Git Diff Repository view
        \li Right-click a changed line and select \uicontrol {Stage Chunk} to add
            the \e {chunk} to the staging area or \uicontrol {Stage Selection}
            to add the selected lines there.
        \li To commit the staged changes to the local repository, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository}
            and select \uicontrol Commit.
            \image {qtcreator-git-commit.webp} {Git Commit view}
            \caption Git Commit view
        \li Select the files to commit, and then select
            \uicontrol {Commit <n/m> File(s)} to commit the changes to the local
            repository.
        \li To push the committed changes to a remote repository, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository}
            and select \uicontrol Push.

            If the local branch does not have an upstream branch in the remote
            repository, \QC prompts you to create it and set it as \e origin.
    \endlist

    \section1 Commit to an existing repository

    To commit and push your first change to an existing repository:

    \list 1
        \li To pull changes from a remote repository, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Remote Repository} and select
            \uicontrol Pull.
        \li Select \uicontrol {Stash & Pop} to stash all local changes before
            pulling and to apply your stash on top of the pulled working tree
            state.
        \li To commit the changes to the local repository, go to \uicontrol Tools
            > \uicontrol Git > \uicontrol {Local Repository} and select
            \uicontrol Commit.
        \li To push the committed changes to a remote repository, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository}
            and select \uicontrol Push.
    \endlist

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-initialize-git-repo.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-general

    \title Initialize Git repositories

    To start controlling a project directory that is currently not under
    version control, go to \uicontrol Tools > \uicontrol Git, and then select
    \uicontrol {Create Repository}.

    \QC creates a new subdirectory named \c {.git} that has all the necessary
    repository files.

    However, Git does not track anything in the project yet, so you need to
    create an initial commit to start tracking the project files.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-diff.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file
    \ingroup creator-how-to-git-current-project
    \ingroup creator-how-to-git-local-repository

    \title git diff

    You can \e {diff} the current file or project to compare it with the latest
    version stored in the repository and to display the differences.

    \list
        \li To view changes in the current file, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Current File} and select
            \uicontrol {Diff of <file>}.
        \li To view changes in a specific file, right-click it in \l {Projects} or
            \l {File System} and select \uicontrol Git > \uicontrol Diff.
        \li To view changes in the current project directory, go to
            \uicontrol Tools > \uicontrol Git >
            \uicontrol {Current Project Directory} and select
            \uicontrol {Diff Directory of <project directory>}.
        \li To view changes in the local repository, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Local Repository} and select
            \uicontrol {Diff}.
    \endlist

    The \uicontrol {Git Diff} view shows the diff in a read-only editor. If \QC
    can access the file, you can double-click a diff chunk to open an editor
    that displays the file and line.

    \image {qtcreator-git-diff-repository.webp} {Git Diff Repository view}
    \caption Git Diff Repository view

    \section1 Fold diff chunks

    To fold all diff chunks, select \inlineimage {icons/qtcreator-expand.png} {Fold All}
    (\uicontrol {Fold All}) from the toolbar. This collapses all diff chunks in
    the \uicontrol {Git Diff} view, making it easier to navigate large diffs.

    \section1 Toggle unified and side-by-side views

    The \uicontrol {Git Diff} view displays the diff side-by-side. To use
    the unified diff view instead, select the
    \uicontrol {Switch to Unified Diff Editor} (1) option from the toolbar.

    \section1 Show Git status in the Projects view

    To show changed files in the \l {Projects} view in a different color, go to
    \preferences > \uicontrol {Version Control} > \uicontrol {General} and select
    \uicontrol {Show VCS file status}.

    \section1 Stage and unstage changes

    Stage your changes to commit them, so that you can push them to the remote
    repository or send them to Gerrit for review. To stage changes for a commit
    chunk-by-chunk or line-by-line, right-click a chunk or line in the
    \uicontrol {Git Diff} view and select context menu commands to stage or
    unstage it.

    \table
        \header
            \li Context Menu Item
            \li Description
        \row
            \li \uicontrol {Revert Chunk}
            \li Resets the changes in the chunk.
        \row
            \li \uicontrol {Stage Chunk}
            \li Adds the chunk to the staging area.
        \row
            \li \uicontrol {Stage Selection}
            \li Adds the selected lines to the staging area.
        \row
            \li \uicontrol {Unstage Chunk}
            \li Removes the chunk from the staging area.
        \row
            \li \uicontrol {Unstage Selection}
            \li Removes the selected lines from the staging area.
    \endtable

    To view a diff of staged changes:

    \list
        \li To view staged changes in the current file, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Current File} and select
            \uicontrol {Diff Staged Changes in <file>}.
        \li To view staged changes in the current project directory, go to
            \uicontrol Tools > \uicontrol Git >
            \uicontrol {Current Project Directory} and select
            \uicontrol {Diff Staged Directory of <project directory> Changes}.
        \li To view staged changes in the local repository, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} and
            select \uicontrol {Diff Staged}.
    \endlist

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-log.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file
    \ingroup creator-how-to-git-current-project
    \ingroup creator-how-to-git-local-repository

    \title git log

    You can view the versioning history of the current file or project directory
    or local repository.

    \list
        \li To view the versioning history of the current file, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} and
            select \uicontrol {Log of <file>}.
        \li To view the versioning history of a selection of the current file, go
            to \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} and
            select \uicontrol {Log of <file> Selection}.
        \li To view the versioning history of the current project directory, go
            to \uicontrol Tools > \uicontrol Git >
            \uicontrol {Current Project Directory} and select
            \uicontrol {Log of <project directory name>}.
        \li To view the versioning history of the local repository, go to
            \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} and
            select \uicontrol {Log}.
        \li To view the log of a directory and its subdirectories or a specific
            file, right-click it in \l Projects or \l {File System} and select
            \uicontrol Git > \uicontrol Log.
    \endlist

    The \uicontrol {Git Log} view shows the commit identifier, author, date, and
    commit message.

    \image {qtcreator-git-log.webp} {Commit details in Git log}

    To set the maximum number of log entries to show, go to \preferences >
    \uicontrol {Version Control} > \uicontrol Git > \uicontrol {Log count}.

    Select \inlineimage {icons/reload_gray.png} {Reload}
    (\uicontrol Reload) to rescan the files.

    \section1 View log entry details

    In the \uicontrol {Git Log} view, select a commit identifier to view commit
    details.

    Right-click a commit identifier to apply actions to the commit.

    \table
        \header
            \li Menu Item
            \li Description
            \li Learn More
        \row
            \li \uicontrol {Add Tag for <hash>}
            \li Add a tag reference to the change. You can add an annotation to
                the tag.
            \li
        \row
            \li \uicontrol {Checkout <hash>}
            \li Check out the commit in a headless state.
            \li
        \row
            \li \uicontrol {Cherry-Pick <hash>}
            \li Cherry-pick the selected commit to the current branch.
            \li
        \row
            \li \uicontrol {Create branch from <hash>}
            \li Create a branch based on the commit.
            \li \l {git branch}
        \row
            \li \uicontrol {Copy <hash>}
            \li Copy the commit <hash> to the clipboard.
            \li
        \row
            \li \uicontrol {Describe Change <hash>}
            \li View a description of the change including the diff in the
                \uicontrol {Git Show} view.
            \li
        \row
            \li \uicontrol {Diff Against <hash>}
            \li Show the changes between the commit and the current HEAD.
            \li \l {git diff}
        \row
            \li \uicontrol {Interactive Rebase from <hash>}
            \li Rebase the current branch on top of <hash>, and choose what to do
                with each commit.
            \li \l {Interactive rebase}
        \row
            \li \uicontrol {Log for <hash>}
            \li Show the versioning history the commit.
            \li
        \row
            \li \uicontrol {Reset to Change <hash>}
            \li Reset the working directory to the commit.
            \li \l {git reset}
        \row
            \li \uicontrol {Revert <hash>}
            \li Revert the changes introduced by this commit. All other commits
                remain unchanged.
            \li
        \row
            \li \uicontrol {Save for Diff}
            \li Save to the current commit to prepare for
                \uicontrol {Diff Against Saved <hash>}.
            \li
\row
            \li \uicontrol {Diff Against Saved <hash>}
            \li Show the changes between the commit and the saved <hash>.
            \li \l {git diff}
    \endtable


    \section1 Toggle the diff view

    To toggle the diff view, select \uicontrol Diff.

    \section1 Use the patience diff algorithm

    To use the patience diff algorithm for calculating the differences, select
    \uicontrol Patience.

    \section1 Ignore whitespace changes

    To only show text changes, select \uicontrol {Ignore Whitespace}.

    \section1 Filter log entries

    To filter log entries by the text in the commit message, by strings that
    were added or removed, or by author:

    \list 1
        \li In the \uicontrol {Git Log} view, select \uicontrol Filter.
        \li Enter a search string in \uicontrol {Filter by message},
            \uicontrol {Filter by content}, or \uicontrol {Filter by author}.
        \li Select \uicontrol {Case Sensitive} to make filtering consider case.
    \endlist

    \section1 Show log for all local branches

    To show the log for all local branches (for example, to see all commits
    that touch a file), select \uicontrol All.

    \section1 Follow only the first parent

    To follow only the first parent on merge commits, select
    \uicontrol {First Parent}.

    \section1 Toggle text and graph

    To toggle between textual and visual representation of the log, select
    \uicontrol Graph.

    \section1 Toggle colors

    To toggle color coding of different parts of the log entries, select
    \uicontrol Color.

    \section1 Show log for previous names of the file

    To show log also for previous names of the file, select \uicontrol Follow.

    \section1 Show details

    To display a description of the change including the diff in the
    \uicontrol {Git Show} view, select \uicontrol {Describe Change <hash>} in the
    context menu.

    \image {qtcreator-vcs-show.png} {Commit description in Git Show}

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-blame.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file

    \title git blame

    By default, each line is annotated in the editor when you move the cursor
    through a file. Hover over the annotation to view commit details and to apply
    actions to the commit.

    \image {qtcreator-git-instant-blame.webp} {Instant blame in the code editor}
    \caption Instant blame in the code editor

    When instant blame is off, you can go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Current File} > \uicontrol {Instant Blame} to view blame for the
    current line.

    \section1 Hide blame in the editor

    To hide blame in the editor, go to \preferences >
    \uicontrol {Version Control} > \uicontrol Git and
    clear \uicontrol {Instant Blame}.

    \image {qtcreator-preferences-vcs-git.webp} {Git tab in Version Control preferences}

    \section1 View blame for the whole file

    To view blame for all lines in the file in the \uicontrol {Git Blame} view,
    go to \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} and
    select \uicontrol {Blame for <file>}. Before each line, you can see
    the identifier of the commit it originates from.

    \image {qtcreator-git-blame.webp} {Git Blame view}

    To hide the path information in the view, select \uicontrol {Omit Path}.

    To hide the author information in the view, select \uicontrol {Omit Author}.

    To hide the date and time information in the view, select
    \uicontrol {Omit Date}.

    To find the commit that introduced the last real code change, select
    \uicontrol {Ignore Whitespace}.

    To find the commit that introduced a line before it was moved, select
    \uicontrol {No Move Detection}. To view moved or copied lines within a file
    or between files, select \uicontrol {Detect Moves Within File},
    \uicontrol {Detect Moves Between Files},
    or \uicontrol {Detect Moves and Copies Between Files}.

    To rescan the files, select \inlineimage {icons/reload_gray.png} {Reload}
    (\uicontrol Reload).

    Select the commit identifier to show a detailed description of the change
    in the \uicontrol {Git Show} view.

    Right-click the commit identifier to \l{Apply actions to commits}
    {apply other actions to the commit}, such as cherry-pick, checkout,
    or revert it.

    \section1 View blame in previous versions

    To show the annotation of a previous version, right-click the commit
    identifier and select \uicontrol {Blame Parent Revision}. This allows you
    to navigate through the history of the file and obtain previous versions
    of it.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-stage-changes.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file
    \ingroup creator-how-to-git-current-project

    \title Stage changes

    Stage your changes to commit them, so that you can push them to the remote
    repository or send them to Gerrit for review.

    \section1 Show file status

    By default, \QC displays the file status in the \l {Projects}, \l {File System},
    and \l {Open Documents} views. The status is refreshed automatically every
    10 seconds.

    To customize how often the file status is updated:

    \list 1
        \li Go to \preferences > \uicontrol {Version Control} >
            \uicontrol General.
        \li Ensure \uicontrol {Show VCS file status with refresh interval}
            is selected.
        \li Set the interval (in seconds) at which \QC requests file status
            updates from Git.
    \endlist

    \section1 Stage the current file

    To mark a new or modified file for committing it to the repository, stage
    the file in one of the following ways:

    \list
        \li Go to \uicontrol Tools > \uicontrol Git > \uicontrol {Current File}
            and select \uicontrol {Stage <file> for Commit}.
        \li Right-click the file in \l {Projects} or \l {File System}
            and select \uicontrol Git > \uicontrol Stage.
        \li Go to \uicontrol Tools > \uicontrol Git >
            \uicontrol {Local Repository} > \uicontrol Commit, right-click
            the file in \uicontrol Files and select \uicontrol Stage.
    \endlist

    \section1 Unstage the current file

    To remove the current file from the staged changes, unstage the file in
    one of the following ways:

    \list
        \li Go to \uicontrol Tools > \uicontrol Git > \uicontrol {Current File}
            and select \uicontrol {Unstage <file> from Commit}.
        \li Right-click the file in \l {Projects} or \l {File System}
            and select \uicontrol Git > \uicontrol Unstage.
        \li Go to \uicontrol Tools > \uicontrol Git >
            \uicontrol {Local Repository} > \uicontrol Commit, right-click
            the file in \uicontrol Files and select \uicontrol Unstage.
    \endlist

    \section1 Stage chunks or lines

    You can stage changes for a commit chunk-by-chunk or line-by-line in the
    \l{git diff}{Git Diff} view.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-reset.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file
    \ingroup creator-how-to-git-local-repository

    \title git reset

    Git uses an index to stage changes. The index is committed on
    the next commit. Git allows you to revert back to the state of the last
    commit as well as to the state staged in the index.

    \section1 Reset all uncommitted changes in the current file

    To undo all unstaged changes and reset the current file to the state of the
    index, go to \uicontrol Tools > \uicontrol Git > \uicontrol {Current File}
    and select \uicontrol {Undo Unstaged Changes for <file>}.

    To return the current file to the state it was in right after the last
    commit, select \uicontrol {Undo Uncommitted Changes for <file>}. This reverts
    all changes, discarding the index.

    \section1 Reset changes in the local repository

    To reset changes in the local repository, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Local Repository} and select \uicontrol Reset.

    Select the commit to reset the working directory to. This is useful
    after applying patches for review, for example.

    Select the reset type:

    \list
        \li \uicontrol Hard reset discards all changes to tracked
            files in the working tree.

            For more information about how to recover accidently removed commits,
            see \l{git reflog}.
        \li \uicontrol Mixed reset undoes the selected commits and unstages all
            changes, but keeps the working tree unchanged.
        \li \uicontrol Soft reset undoes the selected commits but keeps all
            staged changes and the working tree unchanged.
    \endlist

    To recover removed files, select \uicontrol {Recover Deleted Files}.

    \section1 Revert commits in the editor

    To revert the commit you are currently hovering over, select
    \uicontrol {Revert <hash>} in the annotation view.

    \image {qtcreator-git-instant-blame.webp} {Instant blame in the code editor}
    \caption Actions in the annotation view for instant blame

    You are asked to confirm the reversion.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-clean.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-project
    \ingroup creator-how-to-git-local-repository

    \title git clean

    You can remove files that are not under version control from the project
    or local repository.

    \list
        \li To clean the current project directory, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Clean Directory of Project <name>}
            and select \uicontrol {Current Project Directory}.
        \li To clean the local repository, go to \uicontrol Tools >
            \uicontrol Git > \uicontrol {Local Repository} and select
            \uicontrol Clean.
    \endlist

    To clean the directory or repository:

    \list 1
        \li In the \uicontrol {Clean Repository} dialog, select the files to
            delete.
            \image {qtcreator-git-clean-repository.webp} {Clean Repository dialog}
            By default, ignored files are not selected.
        \li Select \uicontrol Delete to remove the selected files.
    \endlist

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-reflog.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git reflog

    Reference logs record the time when the tips of branches and other references
    were updated in the local repository. To view the reference log, go to
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} and select
    \uicontrol Reflog.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-status.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git status

    To view the status of the repository in \uicontrol {Version Control}, go to
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} and select
    \uicontrol Status.

    To include untracked files, select
    \uicontrol {Status (Including All Untracked)}.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-commit.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git commit

    To submit your changes to Git:

    \list 1
        \li Go to \uicontrol Tools > \uicontrol Git >
            \uicontrol {Local Repository} and select \uicontrol Commit.
            \image {qtcreator-git-commit.webp} {Git Commit view}
            \uicontrol {General Information} shows the names of the
            repository and branch for the commit.
        \li In \uicontrol {Commit Information}, check and edit information about
            the author of the changes.
        \li To bypass pre-commit and commit message hooks, select
            \uicontrol {Bypass hooks}.
        \li If your project uses signoffs, select \uicontrol {Sign off} to add a
            \e signed-off-by trailer by the author at the end of the commit log
            message.
        \li In \uicontrol Description, enter a commit message.
        \li In \uicontrol Files, select the files to include in the commit.
        \li Select \uicontrol {Diff Selected Files} to open the \l{git diff}
            {Git Diff Files} view, where you can view the changes and stage them
            chunk-by-chunk or line-by-line.
        \li Select \uicontrol Commit to start committing.
    \endlist

    To view the log of the current branch, select the branch name in
    \uicontrol {Branch}.

    \section1 Apply actions to files

    Open the context menu in \uicontrol Files to apply actions to files. Actions like
    \uicontrol {Open in Editor} and \uicontrol {Show in File System} are provided for all
    files. The availability of other actions depends on the state of the selected file.

    \table
    \header
        \li Menu Item
        \li Description
    \row
        \li \uicontrol Add
        \li Add untracked files to version control.
    \row
        \li \uicontrol Stage
        \li Stage a modified file for commit.
    \row
        \li \uicontrol Unstage
        \li Unstage a modified file.
    \row
        \li \uicontrol Remove
        \li Delete untracked files.
    \row
        \li \uicontrol {Add to .gitignore}
        \li Add untracked files to the ignore list.
    \row
        \li \uicontrol {Mark Untracked}
        \li Mark added files as untracked.
    \row
        \li \uicontrol {Revert Unstaged Changes to <file>}
        \li Revert unstaged changes in modified files to the previous state.
    \row
        \li \uicontrol {Revert All Changes to <file>}
        \li Revert all changes in modified files to the previous state.
    \row
        \li \uicontrol {Recover <file>}
        \li Restore files deleted from version control.
    \row
        \li \uicontrol {Run Merge Tool}
        \li Launch the merge tool to resolve conflicts in the file.
    \row
        \li \uicontrol {Revert Renaming}
        \li Revert renamed files to their previous names.
    \endtable

    \section2 Resolve conflicts

    To resolve conflicts, select \uicontrol {Run Merge Tool} in the context
    menu of a conflicted file and then select one of the following options:

    \table
    \header
        \li Menu Item
        \li Description
    \row
        \li \uicontrol {Resolve by Recovering}
        \li Restore deleted files from version control.
    \row
        \li \uicontrol {Resolve by Removing}
        \li Delete files from version control.
    \row
        \li \uicontrol {Resolve Conflicts with Ours}
        \li Choose \e our version of the file to resolve merge conflicts.
    \row
        \li \uicontrol {Resolve Conflicts with Theirs}
        \li Choose \e their version of the file to resolve merge conflicts.
    \row
        \li \uicontrol {Mark Conflicts Resolved}
        \li Mark the file as resolved after manually resolving the conflicts.
    \endtable

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-am.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git am

    To apply latest changes to the last commit, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Local Repository} >
    \uicontrol {Amend Last Commit}.

    \image {qtcreator-git-amend.webp} {Amending a Git commit}

    To view the log of the current branch, select the branch name in
    \uicontrol Branch.

    To view the commit in its current form before amending, select
    \uicontrol {Show HEAD}.

    To view a diff of the changes in the selected files, select
    \uicontrol {Diff Selected Files}.

    Select \uicontrol Commit to amend the commit.

    \section1 Amend related commits

    To amend an earlier comment in a series of related commits, select
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
    \uicontrol {Fixup Previous Commit}. This operation uses interactive
    rebase. In case of conflicts, a merge tool is suggested.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-interactive-rebase.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title Interactive rebase

    To change a series of commits in the local repository, go to \uicontrol Tools
    > \uicontrol Git > \uicontrol {Local Repository} and select
    \uicontrol {Interactive Rebase}. You can reorder or discard commits, squash
    them into a single commit, or edit the commit messages.

    \section1 Rebase from the change log

    If you already pushed the local changes to a remote repository, \QC refuses
    the interactive rebase because the local commits are missing.

    To start the interactive rebase from the change log, go to \uicontrol Tools
    > \uicontrol Git > \uicontrol Branches > \uicontrol Log. Select the change,
    and then select \uicontrol {Interactive Rebase from <hash>} in the context
    menu.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-branch.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git branch

    To work with Git branches, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Local Repository} and select \uicontrol {Branches}.

    The \uicontrol {Git Branches} view shows a list of branches, as well
    as the differences between your local branches and their origin.
    The branch you checked out is shown in bold and underlined.

    \image {qtcreator-git-branches.webp} {Git Branches view}

    \section1 Filter entries and tags

    Old entries and tags are filtered out of the list of branches
    by default. To include them, select \inlineimage {icons/filtericon.png} {Filter}
    (\uicontrol {Filter}), and then select
    \uicontrol {Include Old Entries} and \uicontrol {Include Tags}.

    To add a tag to a change in the change log, select \uicontrol Branches >
    \uicontrol Log. Select the change, and then select \uicontrol {Add Tag
    for <hash>} in the context menu.

    If you checked out a specific commit, the list of branches displays a
    \e {Detached HEAD} entry.

    For local and remote branches, double-click the branch name to view the
    change log.

    To refresh the list of branches, select
    \inlineimage {icons/reload_gray.png} {Refresh} (\uicontrol Refresh).

    \section1 Add branches

    To create a new tracking or non-tracking branch, select
    \inlineimage {icons/plus.png} {Add Branch} (\uicontrol {Add Branch}).

    \image {qtcreator-git-add-branch.webp} {Add Branch dialog}

    To check out the branch when creating it, select
    \uicontrol {Checkout new branch}.

    To track the selected branch, select \uicontrol {Track local branch}.

    \section1 Manage branches

    The context menu for a branch has the following functions:

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li \uicontrol{Add}
            \li Create new tracking and non-tracking branches.
        \row
            \li \uicontrol{Remove}
            \li Remove a local branch. You cannot delete remote branches.
        \row
            \li \uicontrol Rename
            \li Rename a local branch or a tag. You cannot rename remote
                branches.
        \row
            \li \uicontrol{Checkout}
            \li Check out the selected branch and make it current. You can stash
                changes you have made to tracked files.
        \row
            \li \uicontrol{Diff}
            \li Show the differences between the selected and the current
                branch.
        \row
            \li \uicontrol{Log}
            \li Show the changes in a branch.
        \row
            \li \uicontrol Reset
            \li Reset the active branch to the selected branch. You
                can choose between a \uicontrol Hard, \uicontrol Mixed,
                and \uicontrol Soft reset. For more information, see
                \l{git reset}.
        \row
            \li \uicontrol Merge
            \li Join the development histories in two branches together.
        \row
            \li \uicontrol Rebase
            \li Copy local commits to the updated upstream head.

        \row
            \li \uicontrol {Cherry-Pick}
            \li Select commits to cherry-pick from the selected branch.
        \row
            \li \uicontrol Track
            \li Set the current branch to track the selected one.
        \row
            \li \uicontrol Push
            \li Push the committed changes to the selected remote branch.
    \endtable

    The context menu for a remote branch has the following additional
    functions. To open it, select \uicontrol{Remote Branches} or a remote
    repository.

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li \uicontrol{Fetch}
            \li Fetch all the branches and changes information from a
                specific remote repository, or from all remotes if applied
                to \uicontrol {Remote Branches}.
        \row
            \li \uicontrol{Manage Remotes}
            \li Open the \uicontrol Remotes dialog.
    \endtable

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-merge.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git merge

    To join the development histories in two branches together, go to
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository}
    and select \uicontrol {Branches}.

    In the \uicontrol {Git Branches} view, right-click a remote branch, and
    then select a merge option in the context menu. If the commit you are merging
    can be reached by following the history of the first commit, there is no divergent
    work to merge together. To allow Git to move the branch pointer forward,
    select \uicontrol {Merge <remote branch> into <local branch> (Fast-Forward)}.
    If you do not want to fast-forward the branch, select
    \uicontrol {Merge <remote branch> into <local branch> (No Fast-Forward)}.

    \section1 Configure merge tools

    Only graphical merge tools are supported. You can configure the
    merge tool to use on the command line. For example, to use the
    \l{http://kdiff3.sourceforge.net/}{KDiff3} merge tool, enter the
    following command:

    \badcode
    git config --global merge.tool kdiff3
    \endcode

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-apply-patch.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title Create and apply patches

    Patches are rewriting instructions that Git can apply to a set of files.

    To generate patch files from local commits:
    \list 1
        \li Go to \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository}.
        \li Select \uicontrol Patch > \uicontrol {Create from Commits}.
        \li Select the commits for patch file creation in the dialog.
        \li Select \uicontrol OK.
    \endlist

    The patch files are generated in the root directory of the local repository and
    follow the scheme \e {NNNN-Title-of-Commit.patch}, where \e {NNNN} is a four digit
    number starting with \e {0000}.

    To apply a patch file that is open in \QC, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Local Repository} and select \uicontrol Patch >
    \uicontrol {Apply from Editor}.

    To select the patch file to apply from the file system, select
    \uicontrol {Apply from File}.

    To apply a patch from the clipboard, select \uicontrol {Apply from Clipboard}.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-stash.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-local-repository

    \title git stash

    With Git, you can put your current set of changes onto a virtual shelf
    called a \e stash. Stashes are useful, for example, to put aside a set of
    changes to work on higher priority tasks or to pull in new changes from
    another repository.

    \section1 Stash local changes

    To stash all local changes, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Local Repository} > \uicontrol Stash and select \uicontrol Stash.
    The working copy is reset to the state it had after the last commit.

    To save the current state of your unstaged files and reset the repository to
    its staged state, select \uicontrol {Stash Unstaged Files}.

    \section1 Manage stashed changes

    To display a dialog that shows all known stashes with options to restore,
    display or delete them, select \uicontrol Stashes.

    \section1 Take a snapshot

    To save a snapshot of your current work under a name for later reference,
    select \uicontrol {Take Snapshot}. The working copy is not changed. For
    example, if you want to try something and find out later that it does not
    work, you can discard the changes and return to the state of the snapshot.

    \section1 Pop stashes

    To remove a single stashed state from the stash list and apply it on top of
    the current working tree state, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Local Repository} > \uicontrol Stash and select
    \uicontrol {Stash Pop}.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-commits.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-commits

    \title Apply actions to commits

    To browse a directory or the commit history and to apply actions on the
    commits, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Actions on Commits}.

    \image {creator-git-commit-actions.png} {Select a Git Commit dialog}

    You can apply the following actions on commits:

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li \uicontrol Archive
            \li Package the commit as a ZIP or tarball.
        \row
            \li \uicontrol Checkout
            \li Check out the change in a headless state.
        \row
            \li \uicontrol {Cherry Pick}
            \li Cherry-pick the selected change to the local repository.
        \row
            \li \uicontrol Revert
            \li Revert the changes introduced by the commit. All other commits
                remain unchanged.
        \row
            \li \uicontrol Show
            \li Show the commit in the diff editor.
    \endtable

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-fetch.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-remote-repository

    \title git fetch

    To fetch all the branches and change information from a remote repository,
    go to \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} and
    select \uicontrol Fetch.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-pull.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-remote-repository

    \title git pull

    To pull changes from a remote repository, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository} and select \uicontrol Pull.

    If you have modified files, you are asked how to handle them.

    \section1 Manage uncommitted changes

    \image {qtcreator-git-uncommitted-changes-found.webp} {Uncommitted Changes Found dialog}

    You can apply the following actions to uncommitted changes:

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li \uicontrol {Diff & Cancel}
            \li View a diff of the changes and cancel \c {git pull}.
        \row
            \li \uicontrol {Discard}
            \li Reset local changes and execute \c {git pull}. The changes will
                be lost.
        \row
            \li \uicontrol {Ignore}
            \li Execute \c {git pull} with local changes in the working
                directory.
        \row
            \li \uicontrol {Show/Hide Details}
            \li Show or hide details of the local changes.
        \row
            \li \uicontrol {Stash}
            \li Stash the local changes and execute \c {git pull}.
        \row
            \li \uicontrol {Stash & Pop}
            \li Stash the local changes, execute \c {git pull}, and then pop
                the changes.
    \endtable

    \section1 Pull with rebase

    Go to \preferences > \uicontrol {Version Control} > \uicontrol Git, and then
    select \uicontrol {Pull with rebase} to perform a rebase operation while
    pulling.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-push.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-remote-repository

    \title git push

    To push committed changes to the remote repository, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository} and select \uicontrol Push.

    If the local branch does not have an upstream branch in the remote
    repository, \QC prompts you to create it and set it as upstream.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-instant-blame.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-current-file

    \title Show instant blame

    Instant blame annotates the current editor line with its author and the date
    this line was last changed. Optionally, the annotation shows the commit
    subject.

    To show instant blame for the current file, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Current File} and select
    \uicontrol {Instant Blame for <file>}.

    \note Instant blame is not available for unsaved files.

    To show the latest real changes to the line, configure instant blame to ignore
    whitespace changes and line moves.

    When you hover over the annotation, a tooltip with additional information is shown.
    From the tooltip, the following actions are available:

    \table
        \header
            \li Menu Item
            \li Description
        \row
            \li Blame <hash>
            \li Opens the full file blame for the revision of \e hash.
        \row
            \li Blame Parent
            \li Opens the full file blame for the parent revision of \e hash.
        \row
            \li File at <hash>
            \li Opens the file contents at the revision of \e hash.
        \row
            \li Log for line <line>
            \li Shows a log with all the commits that touched the \e line.
        \row
            \li \inlineimage {icons/copy.png} {Copy Hash to Clipboard}
                (\uicontrol {Copy Hash to Clipboard})
            \li Copies the full \e hash to the clipboard.
        \row
            \li commit <hash>
            \li Opens the commit \e hash with full description and diff.
    \endtable

    \note Most of these actions have no meaning for uncommmited changes.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-with-subversion.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-general

    \title Use Git with Subversion

    You can use Git as a client for a Subversion server. To fetch changes from a
    Subversion repository to a Git repository, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository} > \uicontrol Subversion >
    \uicontrol Fetch.

    \section1 View Git Subversion log

    To view the Git Subversion log, select \uicontrol Log.

    \section1 Publish commits to Subversion

    To publish the commits from the current branch to the Subversion server,
    select \uicontrol DCommit. This will create a revision in Subversion for
    every local Git commit. Afterwards, the branch is rebased or reset
    depending on whether or not there is a diff between Subversion and head.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-gerrit.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-remote-repository

    \title Review code with Gerrit

    If your Git project uses Gerrit for code reviews, you can view your changes
    in \QC.

    To push committed changes to Gerrit, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Remote Repository} >
    \uicontrol {Push to Gerrit}.

    \image {qtcreator-gerrit-push.png} {Push to Gerrit dialog}

    \section1 Push drafts to Gerrit

    Select \uicontrol {Draft/private} to push changes that are
    only visible to you and the reviewers. If you are using Gerrit 2.15 or
    later, you can select \uicontrol {Work-in-progress} to push
    changes that do not generate email notifications.

    \section1 View changes as in Gerrit

    To view the same information about each change as in the Gerrit
    web interface, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Remote Repository} > \uicontrol Gerrit.

    \image {qtcreator-gerrit.png} {Gerrit view}

    \section1 View details of changes

    To view details of the selected change, select \uicontrol Show.

    \section1 Cherry-pick changes

    To cherry-pick the selected change to the local repository, select
    \uicontrol {Cherry Pick}. To remove the change after testing it, select
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
    \uicontrol Reset. In the \uicontrol {Undo Changes to} dialog, select the
    state to reset the working directory to, and then select \uicontrol OK.

    \section1 Checkout changes

    To check out the change in a headless state, select \uicontrol Checkout.

    \section1 Refresh changes

    To refresh the list of changes, select \uicontrol Refresh.

    \uicontrol Remote lists the remotes of the current repository that
    are detected as Gerrit servers. Go to \preferences >
    \uicontrol {Version Control} > \uicontrol Gerrit to specify a fallback
    connection to a Gerrit server over SSH. The Gerrit REST interface and the
    \l{https://curl.haxx.se/}{curl} tool are used for HTTP connections.

    Select \uicontrol HTTPS to prepend \c https to the Gerrit URL
    if Gerrit does not add it.

    \image {qtcreator-preferences-vcs-gerrit.webp} {Gerrit tab in Version Control preferences}

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/

/*!
    \page creator-how-to-git-tools.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-git
    \ingroup creator-how-to-git-general

    \title Git Tools

    \section1 Git Gui

    To start a graphical interface to Git, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Git Tools} > \uicontrol {Git Gui}.

    \note On \macos, the default Git installation does not have Git Gui. To
    use Git Gui, install it separately. To start Git Gui from \QC, go to
    \preferences > \uicontrol {Version Control} > \uicontrol Git, and
    set the path to the environment that has Git Gui in
    \uicontrol {Prepend to PATH}.

    \section1 Gitk

    To start the commit viewer for Git, go to \uicontrol Tools >
    \uicontrol Git > \uicontrol {Git Tools} > \uicontrol Gitk. You can also
    start the tool to view commits in the current document or in the folder that
    has the current document. To specify arguments for running Gitk, go to
    \preferences > \uicontrol {Version Control} > \uicontrol Git.

    \section1 Other repository browsers

    To use some other application for viewing Git history, such as GitX or
    QGit viewer:

    \list 1
        \li Go to \preferences > \uicontrol {Version Control} > \uicontrol Git.
        \li In \uicontrol {Command}, specify the path to the application
            executable.
    \endlist

     To start the application, go to \uicontrol Tools > \uicontrol Git
    > \uicontrol {Git Tools} > \uicontrol {Repository Browser}.

    \section1 Git Bash

    To start Git Bash, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Git Tools} > \uicontrol {Git Bash}.

    \section1 Merge tools

    To resolve merge conflicts, go to \uicontrol Tools > \uicontrol Git >
    \uicontrol {Git Tools} > \uicontrol {Merge Tool}. This menu item is
    visible only when you have merge conflicts to resolve.

    \sa {Use Git}{How to: Use Git}, {Using Git}
*/
