| 1 | alias.*:: |
| 2 | alias.*.command:: |
| 3 | Command aliases for the linkgit:git[1] command wrapper. Aliases |
| 4 | can be defined using two syntaxes: |
| 5 | + |
| 6 | -- |
| 7 | 1. Without a subsection, e.g., `[alias] co = checkout`. The alias |
| 8 | name ("co" in this example) is |
| 9 | limited to ASCII alphanumeric characters and `-`, |
| 10 | and is matched case-insensitively. |
| 11 | 2. With a subsection, e.g., `[alias "co"] command = checkout`. The |
| 12 | alias name can contain any characters (except for newlines and NUL bytes), |
| 13 | including UTF-8, and is matched case-sensitively as raw bytes. |
| 14 | You define the action of the alias in the `command`. |
| 15 | -- |
| 16 | + |
| 17 | Examples: |
| 18 | + |
| 19 | ---- |
| 20 | # Without subsection (ASCII alphanumeric and dash only) |
| 21 | [alias] |
| 22 | co = checkout |
| 23 | st = status |
| 24 | |
| 25 | # With subsection (allows any characters, including UTF-8) |
| 26 | [alias "hämta"] |
| 27 | command = fetch |
| 28 | [alias "rätta till"] |
| 29 | command = commit --amend |
| 30 | ---- |
| 31 | + |
| 32 | With a Git alias defined, e.g., |
| 33 | + |
| 34 | $ git config --global alias.last "cat-file commit HEAD" |
| 35 | # Which is equivalent to |
| 36 | $ git config --global alias.last.command "cat-file commit HEAD" |
| 37 | + |
| 38 | `git last` is equivalent to `git cat-file commit HEAD`. |
| 39 | + |
| 40 | To avoid confusion and troubles with script usage, aliases that |
| 41 | hide existing Git commands are ignored except for deprecated |
| 42 | commands. Arguments are split by |
| 43 | spaces, the usual shell quoting and escaping are supported. |
| 44 | A quote pair or a backslash can be used to quote them. |
| 45 | + |
| 46 | Note that the first word of an alias does not necessarily have to be a |
| 47 | command. It can be a command-line option that will be passed into the |
| 48 | invocation of `git`. In particular, this is useful when used with `-c` |
| 49 | to pass in one-time configurations or `-p` to force pagination. For example, |
| 50 | `loud-rebase = -c commit.verbose=true rebase` can be defined such that |
| 51 | running `git loud-rebase` would be equivalent to |
| 52 | `git -c commit.verbose=true rebase`. Also, `ps = -p status` would be a |
| 53 | helpful alias since `git ps` would paginate the output of `git status` |
| 54 | where the original command does not. |
| 55 | + |
| 56 | If the alias expansion is prefixed with an exclamation point, |
| 57 | it will be treated as a shell command. For example, defining |
| 58 | `alias.new = !gitk --all --not ORIG_HEAD`, the invocation |
| 59 | `git new` is equivalent to running the shell command |
| 60 | `gitk --all --not ORIG_HEAD`. Note: |
| 61 | + |
| 62 | * Shell commands will be executed from the top-level directory of a |
| 63 | repository, which may not necessarily be the current directory. |
| 64 | * `GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` |
| 65 | from the original current directory. See linkgit:git-rev-parse[1]. |
| 66 | * Shell command aliases always receive any extra arguments provided to |
| 67 | the Git command-line as positional arguments. |
| 68 | ** Care should be taken if your shell alias is a "one-liner" script |
| 69 | with multiple commands (e.g. in a pipeline), references multiple |
| 70 | arguments, or is otherwise not able to handle positional arguments |
| 71 | added at the end. For example: `alias.cmd = "!echo $1 | grep $2"` |
| 72 | called as `git cmd 1 2` will be executed as 'echo $1 | grep $2 |
| 73 | 1 2', which is not what you want. |
| 74 | ** A convenient way to deal with this is to write your script |
| 75 | operations in an inline function that is then called with any |
| 76 | arguments from the command-line. For example `alias.cmd = "!c() { |
| 77 | echo $1 | grep $2 ; }; c"` will correctly execute the prior example. |
| 78 | ** Setting `GIT_TRACE=1` can help you debug the command being run for |
| 79 | your alias. |